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About This Manual 



This manual describes CONTROL DATA® CYBIL and CYBIL 
system-resident procedures. CYBIL is the implementation language of 
CDC® Network Operating System/Virtual Environment (NOS/VE). 

NOS/VE provides a program interface consisting of a large number of 
CYBIL procedures. Each CYBIL procedure supplies a specific system 
service to CYBIL programs. Descriptions of the CYBIL procedures are 
topically divided and appear in several manuals, of which this manual 
is one. 

This manual defines the CYBIL language in detail and describes the 
CYBIL Input/Output procedures for reading and writing files and for 
oiner i/u-reiatea iuncuons on oidil programs. 

Audience 

This manual is written for CYBIL programmers. It assumes that you 
understand NOS/VE and System Command Language (SCL) concepts 
as presented in the SCL System Interface and SCL Language 
Definition manuals. 
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The CYBIL Manual Set 

This manual is part of a set of manuals describing CYBIL. 
Descriptions of all manuals in the CYBIL manual set follow: 

CYBIL Language Definition 

Defines the CYBIL language in detail and describes the CYBIL 
Input/Output procedures for reading and writing files and for other 
I/O-related functions on CYBIL programs. 

CYBIL System Interface 

Describes the CYBIL procedures that pertain to command language 
services and processing, program services and management, task 
and job management services, condition processing, message 
generation, interstate communication, limits, and statistics. 

CYBIL File Management 

Describes the CYBIL procedures that assign files to device classes, 
specify attributes for files, and perform file opening, closing, and 
copying. 

CYBIL Sequential and Byte-Addressable Files 

Describes segment and record access, and input/ouput operations to 
sequential and byte-addressable files. 

CYBIL Keyed-File and Sort/Merge Interfaces 

Describes the following: 

• The interface to NOS/VE keyed-files (files having the 

jujluu a<uu~ i>v4 UUii biai CA.X1UL UUCVt-aVt'COS XX1C Ul gCLl.ULAa.liXUJ.liS J. 

• The interface to NOS/VE Sort/Merge, which is used to sort 
records or merge files of sorted records. 

Organization of This Manual 

This manual is in two parts: 

• Part I, which describes the CYBIL language, is organized by topic, 
based on elements of the language. The first chapter introduces 
the basic elements of the language and refers to the chapter in 
which each element is described. 



• 



Part II explains how to use CYBIL I/O procedures and describes 
each procedure. 
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Uonventions 

The following conventions are used in this manual: 



boldface 



In a command or function format, names and 
required parameters are in boldface tvr>e. 



{name} 



Optional parameters are shown in italics and 
are enclosed by braces. If the parameter is 
optional and can be repeated any number of 
times, it is also followed by several periods: 

{name}... 



UPPERCASE 



numbers 
return 



shift 
vertical bar 



orates aiso maicate mat tne enclosed 
parameters and reserved words are used 
together. For example: 

{offset MOD base} 

is considered a single parameter. 

Except for the braces and periods indicating 
repetition, all other symbols shown in the format 
must be included in the coding. 

Uppercase is used for names of commands, 
functions, and parameters (and their 
abbreviations). Uppercase is also used for names 
of variables, files, system constants, and 
terminal keys and function keys when they 
occur in text. 

All numbers are decimal unless otherwise noted. 

Represents the message transmission key on 
your terminal. Depending on the terminal, this 
key may be the RETURN, NEXT, CR, 
CARRIAGE RETURN, NEW LINE, SEND, or 
ETX key. 

Represents the shift key on your terminal. 

A technical change is indicated by a vertical bar 
next to the change. 
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examples Examples are in lowercase unless uppercase 

characters are required for accuracy. Interactive 
terminal session examples are shown in a type 
font that resembles computer output. 

blue Within interactive terminal sessions, user input 

is printed in blue; system output is printed in 
black. 

Submitting Comments 

There is a comment sheet at the back of this manual. You can use it 
to give us your opinion of the manual's usability, to suggest specific 
improvements, and to report errors. Mail your comments to: 

Control Data Corporation 

Technology and Publications Division ARH219 

4201 North Lexington Avenue 

St. Paul, Minnesota 55126-6198 

Please indicate whether you would like a response. 

If you have access to SOLVER, the Control Data online facility for 
reporting problems, you can use it to submit comments about the 
manual. When entering your comments, use CIL as the product 
identifier. Include the name and publication number of the manual. 
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Control Data's Central Software Support maintains a hotline to assist 
you if you have trouble using our products. If you need help not 
provided in the documentation, or find the product does not perform 
as described, call us at one of the following numbers. A support 
analyst will work with you. 

From the USA and Canada: (800)-343-9903 

From other countries: 612-851-4131 

If you have questions about the packaging and/or distribution of a 
printed manual, write to: 

Control Data Corporation 
Literature and Distribution Services 
308 North Dale Street 
St. Paul, Minnesota 55103 

Or call (612) 292-2101. If you are a Control Data employee, call (612) 

ono oi nn 
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Introduction 1-1 

Program Structure 2-1 

Constant, Variable, Type, and Section Declarations 3-1 

Types 4-1 

Expressions and Statements 5-1 

Functions 6-1 

Procedures 7-1 

Compiling and Formatting Source Code 8-1 

Using the Debug Utility 9-1 
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Introduction 1 

This chapter introduces the basic elements of a CYBIL program and 
refers you to the chapter in which each is further described. 

Declarations 1-1 

Statements 1-3 

CYBIL I/O Procedures 1-3 



Introduction 



A CYBIL program consists of two kinds of elements: declarations and 
statements. Declarations describe the data to be used in the program. 
Statements describe the actions to be performed on the data. 

Declarations and statements are made up of predefined reserved words 
and user-defined names and values. The way you form these elements 
is described in chapter 2, as is the general structure for designing a 
CYBIL program. 

Declarations 

Data can be either constant or variable. You can use the constant 
value itself or give it a name using the constant declaration (CONST). 
Variables are named, initialized, and given certain characteristics with 
the variable declaration (VAR). 

One of the characteristics of a variable is its type, such as integer or 
character. You can use CYBIL's predefined (standard) types or define 
your own types. 

To define a new type or redefine an existing type with a new name, 
use the type declaration (TYPE). Once you have defined a type, 
CYBIL will treat it as a standard data type; If you specify your new 
type name as a valid type in a variable declaration, CYBIL will 
perform standard type checking on it. You can also declare where you 
want certain variables to reside by defining an area called a section, 
Which can ue a read-cmy section or a read/ write section, xhis is done 
with the SECTION declaration. All of these data-related declarations 
are described in chapter 3. 

Many standard types are available, among which integers, 
floating-point numbers, characters, and boolean values. In addition, 
you can use combinations of the standard types to define your own 
data types, for example, a record that contains several fields. The next 
paragraphs summarize the types that are predefined by CYBIL. They 
are described in detail in chapter 4. 
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Declarations 

The standard types can be grouped into three categories: basic, 
structured, and storage. 

The basic types are: 

• Scalar, which are typess that have a specific order. They include 
integer, character, boolean, ordinal (in which you define the 
elements and their order), and subrange (which can be specified for 
any of the scalar types by giving a lower and upper bound). 

• Floating-point (real). 

• Cell, which represents the smallest addressable unit of memory. 

• Pointer, which points to a variable, allowing you to access the 
variable by location rather than by name. 

With these basic types you can construct the structured types: strings, 
arrays, records, and sets. 

• String is a sequence of characters. You can reference a portion of 
a string (called a substring) or a single character within a string. 

• Array is a structure that contains components all of the same 
type. The components of an array have a specific order and each 
one can be referenced individually. 

• Record is a structure that contains a fixed number of fields, which 
may be of different types. Each field has a unique name within 
the record and can be referenced individually. You can also declare 
a variant record that has several possible variations (variants). 
The current value of a field common to all variants, or the latest 
assignment to a specific variant field determines which of the 
variants should be used for each execution. 

• Set is a structure tuat contains elements of a single type. Unlike 
an array, elements in a set have no order and individual elements 
cannot be referenced. A set can be operated on only as a whole. 

Storage types are structures to which variables can be added, 
referenced, and deleted under explicit program control using a set of 
storage management statements. The two storage types are sequence 
and heap. 
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Statements 

Ail of the types mentioned above are considered fixed types; that is, 
there is a definite size associated with each one when it is declared. If 
you want to delay specifying a size until execution time, you can 
declare it as an adaptable type. Then, sometime during execution, you 
assign a fixed size or value to the type. A string, array, record, 
sequence, or heap can be adaptable. 

All of these types are described in chapter 4. 

Statements 

Statements define the actions to be performed on the data you have 
defined. There are four kinds of statements: 

■s. uw uvuvg lulu,..™ uirwi/virt^ii/vu UAivvii^v UltV » fc*i UV \JJL %A. ¥ tt-i XUMlUl 

• Structured statements contain and control the execution of a list of 
statements: The BEGIN statement unconditionally executes a 
statement list. The WHILE, FOR, and REPEAT statements control 
repetitive executions of a statement list. 

• Control statements control the flow of execution. The IF and CASE 
statements execute one of a set of statement lists based on the 
evaluation of a given expression or the value of a specific variable. 
CYCLE, EXIT, and RETURN statements stop execution of a 
statement list and transfer control to another place in the 
program. 

• Storage management statements allocate, access, and release 
variables in sequences (using the RESET and NEXT statements), 
heaps (using the RESET, ALLOCATE, and FREE statements), and 
the run-time stack (using the PUSH statement). 

All of the preceding statements are described in detail in chapter 5, 
along with the operands and operators that can be used in expressions 
within statements and declarations. 

Statements can appear within a program (as described in chapter 2), a 
function, or a procedure. 
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CYBIL I/O Procedures 

A function is a list of statements, optionally preceded by a list of 
declarations. It is known by a unique name and can be called by that 
name from elsewhere in the program. A function performs some 
calculation and returns a value that takes the place of the function 
reference. There are many standard functions defined in CYBIL and 
you can also create your own. Standard functions and rules for 
forming your own functions are described in chapter 6. 

A procedure, like a function, is a list of statements, optionally 
preceded by a list of declarations. It also is known by a unique name 
and can be called by that name from elsewhere in the program. A 
procedure performs specific operations and may or may not return 
values to existing variables. You can use the standard procedures or 
define your own. Chapter 7 describes the standard procedures and 
rules for forming your own procedures. 

Chapter 8 describes how to compile and format CYBIL source code. 
The CYBIL command and directives embedded in the source code 
specify how compilation should be performed. The CYBIL command 
calls the CYBIL compiler, tells it which files to use for input and 
output, and specifies what kind of listing you want. The text-embedded 
compilation directives specify listing options, run-time options, the 
layout of the source text, and which portions of the source text to 
compile. 

The FORMAT. CYBIL_ SOURCE command and other text-embedded 
directives specify how formatting should be performed. For example, 
they indicate the margins and line width, tab settings, and indentation 
to be used in the program listing. 

In summary, chapters 2 through 7 describe the elements within a 
CYBIL program. Chapter 8 describes the commands and directives 
that control how the program is compiled and formatted. 



CYBIL I/O Procedures 

Procedures that perform input to and output from CYBIL programs 
are described in this manual in Part II, Common CYBIL Input/Output. 
Other procedures that perform input and output on CYBIL programs 
are described in the CYBIL File Management manual, the CYBIL 
Sequential and Byte-Addressable Files manual, and the CYBIL 
Keyed-File and Sort/Merge Interfaces manual. 
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Frogram Structure 2 

This chapter describes how to form the individual elements used 
within a program and how to structure the program itself. 

Elements Within a Program 2-1 
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Names 2-3 

Constants 2-5 
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Scope 2-10 
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frogram structure 



This chapter describes how to form the individual elements used 
within a program and how to structure the program itself. 

Elements Within a Program 

This section describes valid characters, CYBIL-defined elements, 
user-defined elements, and syntax. 

Valid Characters 

The characters that can be used within a program are those in the 
ASCII character set that have graphic representations (that is, can be 
printed). This character set is included in appendix C. It contains 
uppercase and lowercase letters. In names that you define, you can 
use uppercase and lowercase letters interchangeably. For example, the 
name LOOP_ COUNT is equivalent to the name loop_ count. 

CYBIL-Defined Elements 

CYBIL has predefined meanings for many words and symbols. You 
cannot redefine or use these words and symbols for other purposes. 

A complete list of CYBIL reserved words is given in appendix D. In 
the formats for declarations, type specifications, and statements shown 
in this manual, reserved words are shown in uppercase letters. 
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Elements Within a Program 

The following list includes the reserved symbols and a brief 
description of the purpose of each. They are discussed in more detail 
throughout this manual. 

Symbol Purpose 

+ ,-,*,/,=, Operators used in expressions. They are discussed in 
<, < = , chapter 5. 

>, > = , <>, 

=, Q 

Separates individual declarations and statements. 

Used in declarations as described in chapter 3. 

, Separates repeated parameters or other elements. 

Indicates a reference to a field within a record as 
described in chapter 4. 

Indicates a subrange as described in chapter 4. 

Indicates a pointer reference as described in chapter 

4. 

' ' Delimits a string. 

[ ] Encloses array subscripts, indefinite value 

constructors, and set value constructors as described 
in chapter 4. 



{ } Delimits comments. (Within the formats shown in 

tills manuai. 
parameters.) 



thi& mcLiiual, they are also used to enclose optional 



or ?? Indicates compile-time statements and directives as 

described in chapter 8. 
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Elements Within a Program 

User-Defined Elements 

This section describes names, constants, and constant expressions. 

Names 

You define the names for elements, such as constants, variables, 
types, procedures, and so on, that you use within a program. A name: 

• Can be from 1 to 31 characters in length 

• Can consist of letters, digits, and the special characters # (number 
sign), @ (commercial at sign), _ (underline), and $ (dollar sign) 1 

• Must begin with a letter (there is an exception to this rule for 
system-defined functions and procedures that begin with the # or $ 
character) 

• Cannot contain spaces 

• Cannot be a reserved word (a complete list of CYBIL reserved 
worus is given in appendix D) 

In the formats included in this manual, names that you supply are 
shown in lowercase letters. Within a program, however, there is no 
distinction between uppercase and lowercase letters. The name my_ 
file is identical to the name My_File. 



1. NOS/VE often uses $ in its predefined names. To keep from matching a 
system-reserved name, avoid using $ in the names you define. 
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Elements Within a Program 

There is considerable flexibility in forming names, so you should make 
them as descriptive as possible to promote readability and 
maintainability of the program. For example, LAST_FILE_ 
ACCESSED is more obvious than LASTFIL. 

Examples: 

Valid Names Invalid Names 

SUM ARRAY 

REGISTER#3 FILES&POSITIONS 

POINTER_TABLE 2ND 

The valid names need no explanation. Among the invalid names, 
ARRAY cannot be used because it is a reserved word; 
FILES&POSITIONS contains an invalid character (the ampersand); 
and 2ND does not begin with a letter. 
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Elements Within a Program 



A constant is a fixed value. It is known at compilation time and does 
not change throughout the execution of a program. It can be an 
integer, character, boolean, ordinal, floating-point number, pointer, or 
string. 

Integer constants can be binary, octal, decimal, or hexadecimal. The 
base is specified by enclosing the radix in parentheses following the 
integer, as follows: 

integer (radix) 

Examples are 1011(2) and 19A(16). If the radix is omitted, the integer 
is assumed to be decimal. Integer constants must start with a digit; 

LiiciCiOrc, u Illusb pi e^cuc any IlCAaucunlai ^uusuint uXlat wuiuu 

otherwise begin with a letter, for example, 0FF(16). Negative integer 
constants must be preceded by a minus sign. Positive integer 
constants can be preceded by a plus sign but need not be. 

Integer constants range in value from -(2 63 -l) to 2 63 -l; that is, 
-7FFFFFFFFFFFFFFF hexadecimal through 7FFFFFFFFFFFFFFF 
hexadecimal. 

A character constant can be any single character in the ASCII 
character set. The character is enclosed in apostrophes in the 
following form: 

'character' 

Examples are 'A' and '?'. The apostrophe character itself is specified 
by a pair of apostrophes. 

A boolean constant can be either TRUE or FALSE, each having its 
usual meaning. 

An ordinal constant is an element of an ordinal type that you have 
defined. As a defined element of an ordinal type, it is referred to as 
an ordinal name. For further information, refer to Ordinal under 
Scalar Types in chapter 4. 

Floating-point (real) constants can be written in either decimal 
notation or scientific notation. A real number written in decimal 
notation contains a decimal point and at least one digit on each side, 
for example, 5.123 or -72.18. If the number is positive, the sign is 
optional; if negative, the sign is required. 
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Elements Within a Program 

A real number written in scientific notation is represented by a 
number (the coefficient), which is multiplied by a power of 10 (the 
exponent) in the form: 

coefficientEexponent 

The prefix E is read as "times 10 to the power of." For example, 

5.1E6 

is 5.1 times 10 to the power of 6, or 5,100,000. The decimal point in 
the coefficient is optional. A decimal point cannot appear in the 
exponent; it must be a whole number. If the coefficient or exponent is 
positive, the sign is optional; if negative, the sign is required. 

The pointer constant is NIL. It indicates an unassigned pointer. For 
CYBIL on NOS/VE, a pointer is represented partially by an address 
called the process virtual address (PVA). The PVA is represented as a 
packed record consisting of three fields: the ring number, segment 
number, and byte offset. To indicate the NIL pointer constant 
internally, CYBIL sets these three fields to OF hexadecimal, OFFF 
hexadecimal, and 80000000 hexadecimal, respectively. NIL can be 
assigned to a pointer of any type. 

String constants consist of one or more characters enclosed in 
apostrophes in the form: 

'string' 

An example is 'USER1234', a string of eight characters. An apostrophe 
in a string constant is specified by a pair of apostrophes, for example, 
'DON'T. 

String constants can be concatenated by using the reserved word CAT, 
as in: 

'characters. 1' CAT 'characters_2' 

The result is the string 'characters_lcharacters_2\ The CAT 
operation cannot be used with string variables. 
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Elements Within a Program 

A string constant can be empty, that is, a nuii string; for example, 

CONST str = "; 

declares the string constant STR to be a null string. As a result of 
this declaration, the length of STR is set to zero. 

You cannot reference parts (substrings) of string constants. 

Constant Expressions 

Expressions are combinations of operands and operators that are 
evaluated to find scalar or string type values. In a constant 
expression, the operands must be constants, names of constants (that 
you declare using the constant declaration described in chapter 3), or 
other constant expressions within parentheses. Computation is done at 
compilation time and the resulting value used in the same way a 
constant is used. 

The general rules for forming and evaluating expressions are 
described under Expressions in chapter 5. These rules apply to 
constant expressions with the following exceptions: 

• Constant expressions must be simple expressions; terms involving 
relational operators must be delimited with parentheses. 

• The only functions allowed as factors in constant expressions are 
the $INTEGER, $CHAR, SUCC, and PRED functions with constant 
expressions as arguments. 

• Substring references are not allowed. 
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Syntax 

The exact syntax of the language is shown in the formats of 
individual declarations and statements described in the remainder of 
this manual. The following paragraphs discuss general syntax rules. 

Spaces 

Spaces can be used freely in programs with the following exceptions: 

• Names and reserved words cannot contain embedded spaces. 
Normally, constants cannot contain spaces either, but a character 
constant or string constant can. 

• A name, reserved word, or constant cannot be split over two lines; 
it must appear completely on one line. 

• Names, reserved words, and constants must be separated from 
each other by at least one space, or by one of the other delimiters 
such as a parenthesis or comma. 

For further information, refer to Spacing later in this chapter. 

Comments 

Comments can be used in a program anywhere that spaces can be 
used (except in string constants). They are printed in the source 
listing but otherwise are ignored by the compiler. 

A comment is enclosed in left and right braces. It can contain any 
character except the right brace. To extend a comment over several 
lines, repeat the left brace at the beginning of each line. If the right 
brace is omitted at the end of the comment, the compiler ends it 
automatically at the end of the line. 

Example: 

{this comment 
{appears on 
{several lines.} 

Within this manual, the formats for declarations, type specifications, 
and statements use braces to indicate an optional parameter. 
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'unctuatiuil 



A semicolon separates individual declarations and statements. It must 
be included at the end of almost every declaration and statement. The 
single exception is MODEND which can, but need not, end with a 
semicolon if it is the last occurrence of MODEND in a compilation. 
Punctuation for specific declarations and statements is shown in the 
formats in the following chapters. 

Two consecutive semicolons indicate an empty statement, which the 
compiler ignores. Spacing between the semicolons in this case is 
unimportant. 

Spacing 

Declarations and statements can start in any column. In this manual, 
indentations are used in examples to improve readability. It is 
recommended that similar conventions be used in your programs to 
aid in debugging and documentation for yourself and other users. The 
CYBIL source code formatter, described in chapter 8, can help you do 
this by accepting source code you supply as input and formatting it 
for consistency and readability. 

The LEFT and RIGHT directives, described in chapter 8, can be used 
at compilation time to specify the left and right margins of the source 
text. All source text outside of those margins is then ignored. A 
warning diagnostic is issued for every line that exceeds the specified 
right margin. 

A name, reserved word, or constant cannot be split over two lines; 
each must appear completely on one line. 
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Structure of a Program 

This section describes the module structure, scope, module declaration, 
and program declaration. 

Module Structure 

The basic unit that can be compiled is a module and, optionally, 
compilation time statements and directives. A module can, but need 
not, contain a program. Use this general structure for a module: 

MODULE module_name; 
declarations 

PROGRAM program_name; 
declarations 
statements 
PROCEND program_name; 
MODEND module_name; 

Declarations can be constant, type, variable, section, function, and 
procedure declarations. A module can contain any number and 
combination of declarations, but it can contain only one program. The 
program contains the code (that is, the statements) that are actually 
executed. The required module and program declarations are described 
later in this chapter. 

The structure within a module determines the scope of the elements 
you declare within it. 

Scope 

The scope of an element you declare, such as a variable, function, or 
procedure, is the area of code where you can refer to the element and 

j.b nni u\^ ictogiiu.ou. k^upc ab ucwri iiixiA^u uy w.ie way tilt: piOgitliil 

and procedures are positioned in a module and where the elements 
are declared. 

In terms of scope, the programs, procedures, and functions are often 
referred to as blocks (that is, blocks of code). If an element is 
declared within a block, its scope is only that block (unless it is 
externally declared as described later in this section). Outside the 
block, the element is unknown and references to it are not valid. A 
variable declared within a block is said to be local to the block and is 
called a local variable. 
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Structure of a Program 

An element declared at the module level (that is, one that is not 
declared within a program, procedure, or function) has a scope of the 
entire module. It can be referred to anywhere within the module. A 
variable declared at the module level is said to be global and is called 
a global variable. 

A block can contain one or more subordinate blocks. A variable 
declared in an outer block can always be referenced in a subordinate 
block. However, if a subordinate block declares an element of the 
same name, the new declaration applies while inside that block. 
Figure 2-1 illustrates these rules. 



BLOCK 1 

A rtEf*i ADAXir\RI 














BLOCK 2 

B DECLARATION 














BLOCK 3 

C DECLARATION 
D DECLARATION 








BLOCK 4 

D DECLARATION 

















. Variable A can bs referred tc an v whsre 
in block 1, including blocks 2, 3. and 4. 



. Variable B can be referred to only in 
block 2. 



- Variables C and D can be referred to 
anywhere in blocks 3 and 4. 



However, biock 4 again declares a 
variable named 0. This second 
declaration identifies a different 
variable D and is in effect within 
block 4 only. Outside of block 4, 
yet within block 3, the original 
declaration for D applies. 



v'ARIAB: 86/07/10 



Figure 2-1. Scope of Variables Within a Block Structure 

Storage space is allocated for a variable when the block in which it is 
declared is entered. Space is released when an exit is made from the 
block. Because space is allocated and released automatically, these 
variables are called automatic variables. This method of allocation 
becomes more complex when a procedure, for example, calls itself. 
Space for the same variable must be allocated each time the 
procedure is called and entered, yet each of these spaces must be kept 
separate to maintain the integrity of the variable throughout each 
execution of the procedure. More discussion about this recursive 
process appears later in this section. 
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Structure of a Program 

You can specify that storage for a variable remains intact throughout 
execution by including the STATIC attribute when you declare the 
variable. A variable declared in this way is called a static variable. 

A global variable is always static. Because it is declared at the 
outermost level of a module (consider the module to be a block), 
storage for a global variable is allocated throughout execution of the 
module (or block). For further information on automatic and static 
variables, refer to Variable Declaration in chapter 3. 

Storage is allocated dynamically when the number of times a variable 
will occur is unknown. This happens in two cases, the first of which 
is in recursive procedures or functions when the number of recursive 
calls is unknown. In this case, a mechanism called a stack frame is 
used to hold the automatic variables. Stack frames are allocated 
automatically and you need not understand them to use recursive 
procedures and functions. However, a more complete description is 
given in appendix F, The CYBIL Run-Time Environment. 

The second case of dynamic storage allocation is in the use of the 
special storage types heaps and sequences (described in chapter 4) and 
the run- time stack (described in chapter 5). Heaps and sequences 
represent structures to which you can add and delete variables under 
program control. To allocate space in a heap, you use the ALLOCATE 
statement; in a sequence, you use the NEXT statement. The run-time 
stack is a structure to which you can add but not explicitly delete 
variables. To allocate space on the run-time stack, you use the PUSH 
statement. Space is released when the procedure containing the PUSH 
statement completes. All three statements are described in chapter 5 
under Storage Management Statements. 

The one exception to the preceding scope rules is an element declared 
with the XDCL (externally declared) attribute. This attribute means 
the element is declared in one module but can be referred to in 
anotner. j.n tuis case, tnc ioauer uancues tne links between modules. 
For further information on the XDCL attribute, refer to chapter 3. 
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Module Declaration 

Module Declaration 

The module declaration marks the beginning of a module. MODEND 
marks the end of a module. A module can contain at most one 
program declaration and any combination of type, constant, variable, 
section, function, and urocedure declarations. If two or more modules 
are compiled and linked together for execution, there can be only one 
program declaration in all the linked modules. 

Use this format for a module declaration: 

MODULE name; 2 

name 

The name of the module. 

Use this format for MODEND: 
MODEND { name } ; 

name 

The name of the module. This parameter is optional. If used, 
the name must be the same as that specified in the module 
declaration. 

When compiling more than one module, a semicolon is required after 
each occurrence of MODEND except the last one (there it is not 
required, but is recommended). 



2. Some variations of CYBIL available on other operating systems allow an additional 
option, the alias name, in a module declaration. If it is included in a CYBIL program 
run on NOS/VE, this parameter is ignored. 
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Examples: 

The following example shows a module named ONE that contains 
various declarations and a program named MAIN. 

MODULE one; 

declarations 

PROGRAM main; 

declarations 

statements 
PROCEND main; 
MODEND one; 

The following example shows a compilation consisting of three 
modules named ONE, TWO, and THREE. All three modules can be 
compiled and the resulting object modules linked together to form a 
single object module that can then be executed. For readability, the 
module names are included in all occurrences of MODEND. 

MODULE one; 

dec 1 ar at i ons/st at ement s 
MODEND one; 
MODULE two; 

dec l ar at i ons/st at ement s 
MODEND two; 
MODULE three; 

declarations/statements 
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The program declaration marks the beginning of a program. The end 
of a program is marked by a PROCEND statement. A program can 
contain any combination of type, constant, variable, section, function, 
and procedure declarations, and an v statements. If two or more 
modules are compiled and linked together for execution, there can be 
only one program declaration in the linked modules. 

Use this format for a program declaration: 

PROGRAM name {(formal_parameters)} ; 3 

name 

The name of the program. 

formal ^parameters 

One or more optional parameters included if the program is to 
be called by the operating system. They can be in the form 

VAR name {,name}... : type 
/-~™„ /« ? . j i 

and/or 

name {,name}... : type 

{,name {,name}... : type}... 

where name is the name of the parameter and type is the 
type of the parameter, that is, a predefined type (described in 
chapter 4) or a user-defined type (described in chapter 3). 

The first form is called a reference parameter; its value can be 
changed during execution of the program. The second form is 
called a value parameter; its value cannot be changed by the 
program. Both kinds of parameters can appear in the formal 
parameter list; if so, they must be separated by semicolons (for 
example, HNTEGER; VAR ArCHAR). 



3. Some variations of CYBIL available on other operating systems allow an additional 
option, the alias name, in a program declaration. If it is included in a CYBIL program 
run on NOS/VE, this parameter is ignored. 
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Program Declaration 

The optional formal parameter list is included if a CYBIL program is 
to be called by the operating system. It allows the system to pass 
values (for example, a string that represents a command) to a CYBIL 
program. For further information on passing parameters, refer to the 
CYBIL System Interface manual. 

Use this format for PROCEND: 

PROCEND { name } ; 

name 

The name of the program. This parameter is optional. If used, 
the name must be the same as that specified in the program 
declaration. 

Example: 

The following example shows a program named MAIN that contains 
various declarations, including a procedure named SUB_1: 

PROGRAM main; 

declarations 

PROCEDURE SUb_1; 

declarations 

statements 
PROCEND SUb_1; 

statements {The program starts execution here.} 
PROCEND main; 
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Declarations 3 

This chapter describes how you declare constant and variable data 
types and new data types, It also describes how you specify a 
particular section in which to group data. 

Constant Declaration 3-1 

Variable Declaration 3-3 

Attributes ..,...,.,......., 3-6 

Access 3-6 

Scope 3-8 

Storage 3-9 

Initialization 3-14 

Type Declaration 3-18 

Section Declaration 3-20 



constant, variable, Type, and Section 
Declarations 3 

This chapter describes the constant declaration, which defines a name 

tVyF S iranio "f riaf nmrar nndnfTac +■ no wari or\l.o *3o/»l orpHnn «?Vii/»V» Aa'Pi-nac 

a name for a value that can change; and the type declaration, which 
defines a new type of data and gives a name to that type. In addition, 
it also describes the section declaration, which groups variables that 
share common access characteristics. 

Constant Declaration 

A constant, as described in chapter 2, is a fixed value that is known 
at compile time and doesn't change during execution. A constant 
declaration allows you to associate a name with a value and use that 
name instead of the actual constant value. This provides greater 
readability because the name can be descriptive of the constant. 
Constant declarations also provide greater maintainability because the 
constant value need only be changed in one place, the constant 
declaration, not every place it is used in the code. 

Use this format for a constant declaration: 

CONST name = value {,name = value}...; 

name 

The name associated with the constant value. 

value 

The constant value. It can be an integer, character, boolean, 
ordinal, floating-point, pointer, string, or constant expression. 
Rules for forming these values are given under Constants and 
under Constant Expressions in chapter 2. 

You can write several constant declarations, each declaring a single 
constant, or a single declaration declaring several constants where 
each name = value combination is separated by a comma. 

Type is not specified in a constant declaration. The type of the 
constant is the same as the type of the value assigned to it. 

If used, an expression is evaluated during compilation. The expression 
itself can contain other constants. 
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Constant Declaration 

Examples: 

Rather than repeat the value of pi throughout a program, you can use 
a constant declaration to assign a descriptive name (in this case, PI) 
to the value and use that name in subsequent expressions and 
operations. The constant declaration is: 

CONST 

pi = 3.1415927; 

The following example shows a constant declaration containing several 
different types: 

CONST 

first = 1, 
last = 80, 
hex = 0a8(16), 
bit_pattern = 10110101(2), 
f p_number = 1 . 2e3 , 
stop_character = '.', 
continue = TRUE, 
message = 'end of line', 
last_pointer = NIL, 
length = last - first, 
result = (1 * 2) DIV 3; 

Each constant has the same type as the value assigned to it. For 
example, FIRST and LAST are integer types, as is LENGTH, which is 
the result of an expression containing integers. Notice that the value 
of HEX begins with a because integers must begin with a digit. 
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A variable is an element within a program whose value can change 
during execution. The name of the variable stays the same; it is only 
the value contained in the variable that changes. To use a variable, 

Use this format for a variable declaration: 

VAR name {,name}... : {[attributes]} type {:= initial_value} 
{,name {,name}... -.{[attributes]} type {:= initial _value}}..£ 

name 

The name of the variable. Specifying more than one name 
indicates that all of the named variables will have the 
characteristics that follow (attributes, type, and initial_ value). 

attributes 

One or more of the following attributes. If you specify more 
than one, separate them with commas. 

READ 

Access attribute specifying that the variable is a read-only 
variable; the compiler checks to ensure that the value of 
the variable is not changed. If you specify READ, you must 
also specify an initial value. 

XDCL 

Scope attribute specifying that the variable is declared in ' 
this module but can be referenced from another module. 

XREF 

Scope attribute specifying that the variable is declared in 
another module but can be referenced from this module. 



1. Some variations of CYBIL available on other operating systems allow an additional 
option, the alias name, in a variable declaration. If it is included in a CYBIL program 
run on NOS/VE, this parameter is ignored. 
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#GATE 2 

This attribute is undefined for variable declarations. 
However, if you specify #GATE, you must also specify the 
XDCL attribute. 

STATIC 

Storage attribute specifying that storage space for the 
variable is allocated at load time and remains when control 
exits from the block. Static storage is assumed when any 
attributes are specified. 

section_name 

Storage attribute specifying the name of the user-defined 
section in which the variable resides. A variable in a 
section that is defined as read-only is protected by 
hardware, as opposed to software. The section name and its 
read/write attributes must be declared using the section 
declaration (discussed later in this chapter). 

Attributes are described in more detail later in this chapter. 

The attributes parameter is optional. If it is omitted, CYBIL 
assumes the variable can be read and written; can be 
referenced only within the block where it is created; and, 
unless it is declared at the outermost level of a module, is 
automatic (that is, storage for the variable is allocated only 
during execution of the block in which the variable is 
declared). 

type 

Data type defining the values that the variable can have. Only 
values within this data type are allowed. Types are described 
in chapter 4. 



Initial value assigned to the variable. Specify a constant 
expression, an indefinite value constructor (described under 
Initialization later in this chapter), or a pointer to a global 
procedure. Only a static variable can be assigned an initial 
value. Initialization is discussed later in this chapter. 

This parameter is optional. If it is omitted, the variable is 
undefined and filled with the loader's preset value. 



2. This attribute is not supported on variations of CYBIL available on other operating 
systems. 
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declaration. A variable can be declared only once at each block level 
although it can be redefined in another block or in a contained 
(nested) block. 

The type assigned to a variable defines the range of values it can 
take on and also the operations, functions, and procedures that can 
use it. CYBIL checks to ensure that the operations performed on 
variables are compatible with their types. 

Examples: 

The following declarations define a variable named SCORES that can 
be any integer number, a variable named STATUS that can be either 
of the boolean values FALSE or TRUE, and two variables named 
ALPHA! and ALPHA2 that can be characters: 



VAR 




scores : 


integer; 


VAR 




status ■ 


boolean; 


VAR 




alphal : 


char; 


VAR 




alpha2: 


char; 



The declarations for the two character type variables, ALPHAl and 
ALPHA2, could be combined as follows: 

VAR 
alphal, 
alpha2: char; 

To combine all of the variables in one declaration, you could use: 

VAR 

scores: integer, 
status: boolean, 
alphal , 
alpha2: char; 
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Attributes 

Attributes control three characteristics of a variable: 

Attribute Characteristic 

Access Whether the variable can be both read and written 

Scope Where within the program the variable can be 

referenced 

Storage When and where the variable is stored 

Access 

The access attribute that you can specify is READ. A variable 
declared with the READ attribute can only be read. It must be 
initialized in the declaration and cannot be assigned another value 
later. It is called a read-only variable. If the READ attribute is 
omitted, CYBIL assumes the variable can be both read and written 
(changed). 

The READ attribute is enforced by software; that is, the compiler 
checks to ensure that the value of a variable does not change. The 
READ attribute alone does not mean that the variable is actually in a 
read-only section. 3 To do that, you must specify the name of a 
read-only section as declared in a section declaration (described later 
in this chapter). 

A variable with the READ attribute specified is assumed to be static. 
(For further information on static variables, refer to Storage later in 
this chapter.) You can use a read-only variable as an actual 
parameter in a procedure call only if the corresponding formal 
parameter is a value parameter; that is, a read-only variable can be 
passed to a procedure only if the procedure makes no attempt to 
aooigii a. vaiuc u# xl. v,r luwuuie parameters are aescriDea in cnapter 
7.) 



3. A read-only section is a hardware feature. Data that resides in a physical area of 
the machine designated as a read-only section is protected by hardware, not by 
software. This feature is described in further detail in volume II of the virtual state 
hardware reference manual. 
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in the same places. For example, the initial value that you can assign 
to a variable (as described earlier in this chapter) must be a constant 
expression, an indefinite value constructor, or a pointer to a global 
procedure. In this case, even though a read-only variable has a 
constant value, you cannot use it in place of a constant expression. 
Also, as mentioned in chapter 2, you cannot reference a substring of a 
constant. You can, however, reference a substring of a variable and, 
thus, a read-only variable. There are other differences similar to 
these. The descriptions in this manual state explicitly whether 
constants and/or variables can be used. 

Examples: 

In this example the variable DEBUG is a read-only variable set to 
the constant value of TRUE. NUMBER can be read and written. 

VAR 

debug: [READ] boolean := TRUE, 
number: integer: 

The following example illustrates a difference between constants and 

roa^-nnlv vnrinhlAC Tn ftaplarA a ctrincr frvnA umi mnct erwsfM-fV fine 

length of the string in parentheses following its name. As defined in 
chapter 4, the length must be a positive, integer constant expression. 

CONST 

string_size_1 = 5; 

VAR 

string_size_2: [READ] integer := 5, 
stringl: string (string_size_1) , 
string2: string (string_size_2); 

The declaration of STRING1 is valid; the length of the string is 5, 
which is the value of the constant STRING_SIZE_1. However, 
STRING2 is invalid; even though STRING_SIZE_2 does not change 
in value, it is still a variable and cannot be used in place of a 
constant expression. 
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Scope 

The scope attributes define the part or parts of a module to which a 
variable declaration applies. If you don't include any scope attributes 
in the declaration, the scope of a variable is the block in which it is 
declared. A variable declared in an outermost block applies to that 
block and all the blocks it contains. However, a variable declared 
even at the outermost level of a module cannot be used outside of 
that module. Use the scope attributes, XDCL and XREF, to extend the 
scope of a variable so that it can be shared among modules. 

To use the same variable in different modules, you must specify the 
XDCL and XKEF attributes. The XDCL attribute indicates that the 
variable being declared can be referenced from other modules. The 
XREF attribute indicates that the variable is declared in another 
module. When the loader loads modules, it resolves variable 
declarations so that each XDCL variable is allocated static storage 
and the XREF variable shares the same space. This is known as 
satisfying externals. The loader issues an error if an XREF variable 
does not have a corresponding XDCL variable. In one compilation unit 
or group of units that will be combined for execution, a specific 
variable can have only one declaration that contains the XDCL 
attribute. 

Declarations for a shared variable must match except for 
initialization. A variable declared with the XDCL attribute can be 
initialized and have different values assigned during program 
execution. A variable declared with the XREF attribute cannot be 
initialized but can be assigned values. 

If you declare any attributes, the variable is assumed to be static in 
storage. If you don't declare any attributes, the variable is assumed to 
be automatic, unless you declare it at the outermost level of the 
module. (A variable declared at the outermost level is always static.) 
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Assume the following two modules have been compiled. When the 
loader loads the resulting object modules and satisfies externals, it 
allocates storage to FLAG, an XDCL variable, and initializes it to 
FALSE. When the loader finds the XREF variable FLAG in module 
TWO, it assigns the same storage. Thus, references to FLAG from 
either module refer to the same storage location. 

MODULE one; 

VAR 

flag: [XDCL] boolean := FALSE; 

MODEND one; 
MODULE two; 

VAR 

flag: [XREF] boolean; 

MODEND two; 

Storage 

The storage attributes determine when storage is allocated and where 
storage is allocated. 

When Storage is Allocated 

There are two methods of allocating storage for variables: automatic 
and static. For an automatic variable, storage is allocated when the 
block containing the variable's declaration begins execution. Storage is 
released when execution of the block ends. If the block is entered 
again, storage is allocated again, and so on. When storage is released, 
the value of the variable is lost. 

For a static variable, storage is allocated (and initialized, if that 
parameter is included) only once, at load time. Storage remains 
allocated throughout execution of the module. However, even though 
storage remains allocated, a static variable still follows normal scope 
rules. It can be accessed only within the block in which it is declared. 
A reference to a static variable from an outer block is an error even 
though storage for the static variable is still allocated. 
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Attributes 

The ability to declare a static variable is important, for example, in 
the case where an XDCL variable is referenced by a procedure before 
the procedure that declares the variable is executed. Because an 
XDCL variable is static (refer to Scope earlier in this chapter for 
further information), it is allocated space and is initialized 
immediately at load time; therefore, it is available to be referenced 
before execution of the procedure that actually declares it as XDCL. 

A variable can be declared static with the STATIC attribute. It is 
assumed to be static if it is in the outermost level of a module or if 
it has any other attributes declared. In all other cases, CYBIL 
assumes the variable is automatic. Only a static variable can be 
initialized. 

The period between the time storage for a variable is allocated and 
the time that storage is released is called the lifetime of the variable. 
It is defined in terms of modules and blocks. The lifetime of an 
automatic variable is the execution of the block in which it is 
declared. The lifetime of a static variable is the execution of the 
entire module. An attempt to reference a variable beyond its lifetime 
causes an error and unpredictable results. 

The lifetime of a formal parameter in a procedure is the lifetime of 
the procedure in which it is a part. Storage space for the parameter is 
allocated when the procedure is called and released when the 
procedure finishes executing. 

The lifetime of a pointer must be less than or equal to the lifetime of 
the data to which it is pointing. 

The lifetime of a variable that is allocated using the storage 
management statements (described in chapter 5) is the time between 
the allocation of storage and the release of storage. A variable 
allocated by an automatic pointer (using the ALLOCATE statement) 

mnct Ko avnll/»lf1v fraarl fncintr fVio P'RTT.'I?. cfofomanfl \\afn-wa fUr» UIaaU 
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is left, or the space will not be released by the program. When the 
block is left, the pointer no longer exists and, therefore, the variable 
cannot be referenced. If the block is entered again, the previous 
pointer and the variable referenced by the pointer cannot be 
reclaimed. Therefore, it is recommended that you free such variables 
before leaving the block. 
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Attributes 



.EiXainpie: 

In this example, the variables COUNTER and FLAG will exist during 
execution of the entire module; however, they can be accessed only 
within program MAIN. 

PROGRAM main; 

VAR 
counter: [STATIC] integer := 0, 
flag: [STATIC] boolean; 

PROCEND main; 



Where Storage is Allocated 

You can optionally specify that storage for a variable be allocated in 
a particular section. A section is a storage area that can hold 
variables sharing common access attributes, such as read-only 
variables or read/write variables. You can define the section and its 
access attributes yourself using the section declaration (discussed later 
in this chapter). 
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If you define a section with the section READ attribute, you define a 
read-only section in the hardware. 4 Any variable declared with that 
section's name as an attribute will reside in that read-only section. 
When you specify the name of a read-only section in a variable 
declaration, you must also include the variable access attribute READ. 

In addition to any sections you define, CYBIL has several predefined 
sections. You cannot assign a variable to one of these sections 
explicitly, in the sense that you could include the section name as an 
attribute in your variable declarations. Instead, the variable is 
assigned to one of these predefined sections implicitly, based on its 
other attributes and characteristics. For example, all static variables 
that are not assigned to a user-defined section are automatically 
assigned to a section named $STATIC. The following are the CYBIL 
section names and their contents. 



Section 



Description 



$BINDING 

CYB$DEFAULT_HEAP 

^LITERAL 

$PARAMETER 

$REGISTER 



»DmA rvrr 



$STATIC 



The binding section that contains the links 
to external procedures and the data of the 
module. 

The CYBIL default heap. 

Constants. 

A subset of the $STACK section that 
contains parameter list variables. 

Variables that exist only in hardware 
registers. 



Static variables that are not already 
assigned to a user-defined section. 



4. A read-only section is a hardware feature. Data that resides in a physical area of 
the machine designated as a read-only section is protected by hardware, not by 
software. This feature is described in further detail in volume II of the virtual state 
hardware reference manual. 
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Attributes 



Txie bv^L uuject vyOue ivlauageuieiit xnauuai gives lUitner imormatioii 
on sections regarding the object module format expected as input by 
the loader and the object library generator. 

Example: 

This example defines a read-only section named NUMBERS. The 
variable INPUT_ NUMBER is a read-only variable that also resides in 
the section NUMBERS. In the variable declaration, the READ 
attribute causes the compiler to check that the variable is not written; 
the read-only section name, NUMBERS, causes the hardware to 
ensure that the variable is not written. 

SECTION 

numbers: READ; 

VAR 

input_number: [READ, numbers] integer := 100; 
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Initialization 

You can assign an initial value to a variable only if it is a static 
variable. The value can be a constant expression, an indefinite value 
constructor (described next), or a pointer to a global procedure. The 
value must be of the proper type and in the proper range. If you don't 
specify an initial value, the value of the variable is undefined. 

An indefinite value constructor is essentially a list of values. It is 
used to assign values to the structured types: sets, arrays, and 
records. It allows you to specify several values rather than just one. 
Values listed in a value constructor are assigned in order (except for 
sets, which have no order). The types of the values must match the 
types of the components in the structure to which they are being 
assigned. An indefinite value constructor has the form 

[value {,value}...] 

where value can be one of the following: 

• A constant expression 

• Another value constructor (that is, another list) 
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Initialization 



• The phrase 

REP number OF value 

which indicates the specified value is repeated the specified 
number of times 

• The asterisk character (*), which indicates the element in the 
corresponding position is uninitialized 

The REP phrase can be used only in arrays. The asterisk can be used 
only in arrays and records. For further information, refer to the 
descriptions of arrays and records in chapter 4. 

If you assign an initial value to a string variable and the variable is 
longer than the initial value, spaces are added on the right of the 
initial value to fill the field. If the initial value is longer than the 
variable, the initial value is truncated on the right to fit the variable. 

In a variant record, fields are initialized in order until a special 
variable called the tag field name is initialized. The tag field name is 
then used to determine the variant for the remaining field or fields in 
the record, and they are likewise initialized in order. 

Depending on the attributes defined in the variable declaration, 
initialization is required, prohibited, or optional. Table 3-1 shows the 
initialization possible for various attributes. 
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Initialization 



Table 3-1. Attributes and Initialization 



Attributes Specified 1 



Initialization 



None 

READ 

READ.STATIC 

READ,XDCL 

READ,STATIC,XDCL 

READ,section_name 

READ,XDCL,section_name 

XREF 

XREF,READ 

XREF,STATIC 

XREF,READ,STATIC 

STATIC 

XDCL 

XDCL,STATIC 

56c uiGii name 

section_name J XDCL 



Optional if static variable; prohibited if 
automatic variable. 

Required. 

Required. 

Required. 

Required. 

Required. 

Required. 

Prohibited. 

Prohibited. 

Prohibited. 

Prohibited. 

Optional. 

Optional. 

Optional. 






Optional. 



x. j.iic aiam; aunuuie xa aaaumcu u. tmV atuiomes are speciliea. 
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Initialization 



Example: 

The variables declared in this example are inside program MAIN. 
Therefore, they are automatic unless they are declared with an 
attribute. TOTAL is automatic and as such cannot be initialized. 
COUNT is declared static and can be initialized. ALPHA and BETA 
are also static and can be initialized because they have other 
attributes declared. 

PROGRAM main; 
VAR 

total: integer, 

count: [STATIC] integer := 0, 

alpha, 

beta: tXDCL, READ] char := 'p'; 

PROCEND main; 
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Type Declaration 

The standard data types that are defined in CYBIL are described in 
chapter 4. Any of these can be declared as a valid type within a 
variable declaration. The type declaration allows you to define a new 
data type and give it a name, or redefine an existing type with a new 
name. Then that name can be used as a valid type within a variable 
declaration. 

Use this format for a type declaration: 

TYPE name = type {,name = type}...; 

name 

Name to be given to the new type. 

type 

Any of the standard types defined by CYBIL or another 
user-defined type. 

Once you define a type, you can use it to define yet another type. 
Thus, you can build a very complex type that can be referred to by a 
single name. 

The type declaration is evaluated at compilation time. It does not 
occupy storage space during execution. 
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Type Declaration 



riixampies: 



In this example, INT is defined as a type consisting of all the 
integers; it is just a shortened name for a standard type. LETTERS is 
defined as a type consisting of the characters 'a' through 'z' only; this 
is a selective subset of the standard type characters. DEVICES is an 
ordinal type that in turn is used to define EQ_TABLE, a type 
consisting of an array of 10 elements. Any element in the type EQ_ 
TABLE can have one of the ordinal values specified in DEVICES. 

TYPE 

int = integer, 

letters = 'a' .. 'z', 

devices = (lp512, dk844, dk885, nt679), 

eq_table = array [1 .. 10] of devices; 

VAR 

i: int, 

alpha: letters, 

table_l: eq_table, 

status_table: array [1 ..3] of eq_table; 

All of the variables in the preceding example could have been 
declared using variable declarations only, as in: 

VAR 

i: integer, 
alpha: 'a' .. 'z', 

table_l: array [1 .. 10] of (lp512, dk844, dk885, nt679), 
status_table: array [1 .. 3] of array [1 .. 10] of 
(lp512, dk844, dk885, nt679) ; 

However, it becomes cumbersome to declare a complex structure using 
only standard types. Defining your own types lets you avoid needless 
repetition and the increased possibility of errors. In addition, it makes 
code easier to maintain; to add a new device in the first example, you 
only need to add it in the type declaration, not in every variable 
declaration that contains devices. 
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Section Declaration 

A section is an optional working storage area that contains variables 
with common access attributes. You can define a section and its 
associated attributes with the section declaration. Including the section 
name in a variable declaration causes the variable to reside in that 
section. 

Use this format for a section declaration: 

SECTION name {,namej... : attribute 
{,name {,name}... : attribute}..* 

name 

Name of the section. 

attribute 

The keyword READ or WRITE. 

A section defined with the READ attribute is considered a read-only 
section. 5 A variable declared with that section's name will reside in 
read-only memory. In this case, the variable access attribute READ 
must also be included in the variable declaration. The section name 
causes hardware protection; the READ attribute causes compiler 
checking. 

A section defined with the WRITE attribute contains variables that 
can be both read and written. 

The initialization of variables declared with a section name depends 
on "their attributes, as shown in table 3-1. Variables declared with a 
section name are static. 

The names and contents of predefined CYBIL sections are given 
earlier in this section under Where Storage is Allocated. The SCL 
Object Code Management manual gives further information on sections 
regarding the object module format expected as input by the loader 
and the object library generator. 



5. A read-only section is a hardware feature. Data that resides in a physical area of 
the machine designated as a read-only section is protected by hardware, not by 
software. This feature is described in further detail in volume II of the virtual state 
hardware reference manual. 
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Section Declaration 

Example: 

Two sections are defined in this example: LETTERS is a read-only 
section and NUMBERS is a read/write section. The variable 
CONTROL. LETTER is a read-only variable that resides in LETTERS. 
The READ attribute is required because of the read-only section 

~ Q ™„ TTT3n ATI? XTT HI/TO I?!? J„ „ „o««U1« J-U„-t- „„— V.- _„„,; „_ ,„_;**__ 

and resides in the section NUMBERS. In this example, it is also 
declared as an XDCL variable but this is not required. 

SECTION 

letters: READ, 
numbers: WRITE; 

VAR 

update_number : [XDCL, numbers] integer; 



Revision F Declarations 3-21 



Types 4 

This chapter describes the standard types predefined by CYBIL. 

Using Types 4-2 

Equivalent Types 4-3 

Basic Types 4-4 

Scalar Types 4-4 

Integer 4-5 

Character 4-6 

Boolean 4-7 

Ordinal 4-8 

UVi. UUg V * TT—.HJ 

Floating-Point Type 4-12 

Real 4-12 

Cell Type 4-12 

Pointer Types 4-12 

Pointer to Cell 4-18 

Structured Types 4-20 

Strings 4-20 

Substrings 4-21 

Assigning and Comparing String Elements 4-24 

Arrays 4-25 

Initializing Elements 4-26 

Referencing Elements 4-27 

Records 4-29 

Invariant Records 4-30 

Variant Records 4-33 

Initializing Elements 4-38 

Referencing Elements 4-39 

Alignment 4-40 

Sets 4-41 

Initializing and Assigning Elements 4-42 

Storage Types 4-44 

Sequences 4-44 

Heaps 4-46 

Adaptable Types 4-48 

Adaptable Strings 4-49 

Adaptable Arrays 4-49 

Adaptable Records 4-51 



Adaptable Sequences , 4-53 

Adaptable Heaps 4-53 
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Types 4 

There are many standard types defined within CYBIL. A variable can 
be assigned to (that is, be made an element of) any of these types. 
The type defines characteristics of the variable and what operations 
can be performed using the variable. In general, operations involving 
nonequivalent types are not allowed; one type cannot be used where 
another type is expected. Exceptions are noted in the descriptions of 
types that follow. 

In this chapter, types are grouped into three major categories: basic, 
structured, and storage types. 

Basic types are the most elementary. They can stand alone but are 
also used to build the more complex structures. The basic types are: 

• Scalar types (integer, character, boolean, ordinal, and subrange) 

• Floating-point types (real) 

• Cell types 

• Pointer types 

Structured types are made from combinations of the basic types. The 
structured types are: 

• Strings 

• Arrays 

• Records 

• Sets 

Storage types hold groups of components of various types. The storage 
types are: 

• Heaps 

• Sequences 

Most types, when they are declared, have a fixed size. Strings, arrays, 
records, sequences, and heaps can also be declared with an adaptable 
size that is not fixed until execution. For this reason, they are 
sometimes called adaptable types. Adaptable strings, arrays, records, 
sequences, and heaps are discussed at the end of this chapter. 
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Using Types 

Types are used as parameters in two kinds of declarations: the 
variable declaration (to associate a type with a variable name) and 
the type declaration (to associate a type with a new type name). Both 
declarations are described in detail in chapter 3, but their basic 
formats are: 

VAR name : { [attributes] } type { := initial_value } ; 

TYPE name = type; 

The description of each type shown in this chapter includes the 
keyword and any additional information necessary to specify that type 
as a parameter. The keywords replace the generic word type in the 
variable and type declarations. For example, you would use the 
keyword INTEGER to specify an integer type. The variable declaration 
would be: 

VAR name : { [attributes] } INTEGER { := initial _value } ; 

The type declaration would be: 

TYPE name = INTEGER; 
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Equivalent Types 



equivalent xypes 

As mentioned earlier in this chapter, operations involving 
nonequivalent types are not allowed. Two types can be equivalent, 
though, even if they don't appear to be identical. For example, two 

expressions may yield the same value. Rules for determining whether 
types are equivalent are given in the following descriptions of the 
types. 

Adaptable types and bound variant record types (described under 
Records later in this chapter) actually define classes of related types 
that vary by a characteristic, such as size. Adaptable type variables, 
bound variant record type variables, and pointers to both types are 
fixed explicitly at execution time. These types are said to be 
potentially equivalent to any of the types to which they can adapt. 
That is, during compilation, references to adaptable types and bound 
variant record types are allowed wherever there is a reference to one 
of the types to which they can adapt. However, further type checking 
is done during execution when each type is fixed (assigned to a 
specific type). It is the current type of an adaptable or bound variant 
record type that determines what operations are valid for it at any 
given time. 
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Basic Types 

The following describes the basic types. 

Scalar Types 

All scalar types have an order; that is, for every element of a scalar 
type you can find its predecessor and successor. 

Scalar types are made up of five types: 

• Integer 

• Character 

• Boolean 

• Ordinal 

• Subrange 
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Integer 






Use the keyword INTEGER to specify an integer type. 

Integers range in value from -(2 63 -l) to 2 63 -l; that is, 
-7FFFFFFFFFFFFFFF hexadecimal through 7FFFFFFFFFFFFFFF 
hexadecimal. In general, the subrange type should be used rather than 
the integer type. This allows the compiler to perform more rigorous 
type checking and may reduce the amount of storage needed to hold 
the value. 

The operations permitted on integers are assignment, addition, 
subtraction, multiplication, division (both quotient and remainder), all 
relational operations, and set membership. Refer to Operators in 
chapter 5 for further information on operations. 

The functions $INTEGER and $REAL, described in chapter 6, convert 
between integer type and real type. The $CHAR function, also 
described in chapter 6, converts an integer value from to 255 to a 
character according to its position in the ASCII collating sequence. 

Example: 

This example shows the definition of a new type named INT, which 
consists of elements of the type integer. The variable declaration 
declares variable I to be of type INT, which is the integer type just 
declared. Also declared as a variable is NUMBERS, which is explicitly 
of integer type. Because NUMBERS is static, it can be initialized. 

TYPE 

■j nt = \ nts n sr ■ 

VAR 

i: int, 

numbers: [STATIC] integer .= 100; 
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Character 

Use the keyword CHAR to specify a character type. 

An element of the character type can be any of the characters in the 
ASCII character set included in appendix C. It is always a single 
character; more than one character is considered a string. (A string is 
one of the structured types discussed later in this chapter. A string of 
length 1 can sometimes be used as a character. Refer to Substrings 
later in this chapter.) 

The operations permitted on characters are assignment, all relational 
operations, and set membership. A character can be assigned and 
compared to a string of length 1. Refer to Operators in chapter 5 for 
further information on operations and to Strings later in this chapter 
for further information on string assignment. 

The $INTEGER function described in chapter 6 converts a character 
value to an integer value based on its position in the ASCII collating 
sequence. The $CHAR function, also described in chapter 6, converts 
an integer value between and 255 to a character in the ASCII 
collating sequence. 

Example: 

This example shows the definition of a new type named LETTERS, 
which consists of elements of the type character. The variable 
declaration declares variable ALPHA to be of type LETTERS, which is 
the character type; it is static and initialized to the character 'j'. The 
variable IDS is explicitly declared to be of type character. 

TYPE 

letters = char; 

VAR 

alpha: [STATIC] letters := 'j', 
ids: char; 
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Boolean 



Use the keyword BOOLEAN to specify a boolean type. 

An element of the boolean type can have one of two values: FALSE or 
TRUE. As with other scalar types, boolean values are ordered. Their 
order is FALSE, TRUE. FALSE is always less than TRUE. 

You get a boolean value by performing a relational operation on two 
objects of the same type. You can perform some, but not necessarily 
all, relational operations on every type except the following: 

• Arrays or structures that contain an array as a component or field 

• Variant records 

• Sequences 

• Heaps 

• Records that contain a field of one of the preceding types 

The operations permitted on boolean values are assignment, ail 
relational operations, set membership, and boolean sum, product, 
difference, exclusive OR, and negation. Refer to Operators in chapter 5 
for further information on operations. 

The $INTEGER function described in chapter 6 converts a boolean 
value to an integer value. is returned for FALSE; 1 is returned for 
TRUE. 

Example: 

This example shows the definition of a new type named STATUS, 
which consists of the boolean values FALSE and TRUE. The variable 
declaration declares variable CONTINUE to be of type STATUS; that 
is, it can be either FALSE or TRUE. The variable DEBUG is 
explicitly declared to be boolean and, because it is a read-only 
variable and therefore static, it can be initialized. 

TYPE 
status = boolean; 

VAR 
continue: status, 
debug: [READ] boolean := TRUE; 
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Ordinal 

The ordinal type differs from the other scalar types in that you define 
the elements within the type and their order. The term ordinal refers 
to the list of elements you define; the term ordinal name refers to an 
individual element within the ordinal. 

Use this format to specify an ordinal: 

(name, name {,name...} ) 

name 

Name of an element within the ordinal. There must be at least 
two ordinal names. The maximum number of names in a single 
ordinal list is 16,384. 

The order is given in ascending order from left to right. 

Each ordinal name can be used in only one ordinal type. If you use a 
name in more than one ordinal, a compilation error occurs. 

Ordinals are used to improve the readability and maintainability of 
programs. They allow you to use meaningful names within a program 
rather than, for example, map the names to a set of integers that are 
then used in the program to represent the names. 

The operations permitted on ordinals are assignment, all relational 
operations, and set membership. 

Two ordinal types are equivalent if they are defined in terms of the 
same ordinal type names. 

The $INTEGER function described in chapter 6 converts an ordinal 
value (that is, a name) to an integer value based on its position 
within the defined ordinal. The first ordinal name has an integer 
value of 0, the second name an integer value of 1, and so on. 
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Ordinal 



ftxampies: 

In this example, the type declaration defines an ordinal type named 
COLORS, which consists of the elements RED, GREEN, and BLUE. 
The variable PRIMARY. COLORS is of COLORS type and therefore 
has the same elements. The variable WORK_DAYS explicitly declares 
the ordinal consisting of elements MONDAY through FRIDAY. 

TYPE 

colors = (red, green, blue); 

VAR 

primary _colors: colors, 

work_days: (monday, tuesday, Wednesday, thursday, 
friday) ; 

In the ordinal type COLORS, the following relationships hold: 

RED < GREEN 

RED < BLUE 

GREEN < BLUE 

You can find the predecessor and successor of every element of an 
ordinal. You can also map each element onto an integer using the 
$INTEGER function (described in chapter 6). For example, 
$INTEGER(RED) = 0; this is the first element of the ordinal. 

The type declaration 

TYPE 

primary_colors = (red, green, blue), 
hot_colors = (red, orange, yellow); 

is in error because the name RED appears in two ordinal definitions. 
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Subrange 

A subrange is not a new type but a specified range of values within 
an existing scalar type. A variable defined by a subrange can take on 
only the values between and including the specified lower and upper 
bounds. 

Use this format to specify a subrange: 

lowerbound . . upperbound 

lowerbound 

Scalar expression specifying the lower bound of the subrange. 

upperbound 

Scalar expression specifying the upper bound of the subrange. 

The lower bound must be less than or equal to the upper bound. Both 
bounds must be of the same scalar type. 

The type of a subrange is the type of its lower and upper bounds. If a 
subrange completely encompasses its own type, it is said to be an 
improper subrange type. For example, the subrange 

FALSE .. TRUE 

is of type boolean and also contains every element of type boolean. It 
is equivalent to specifying the type itself. An improper subrange type 
is always equivalent to its own type. 

Two subranges are equivalent if they have the same lower and upper 
bounds. 
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Subrange 

Subranges allow for additional error checking. Compilation options are 
available that cause the compiler to check assignments during 
program execution and issue an error if it finds a variable not within 
range. (Range checking is available as an option on the compiler call 
command and as a compiler directive. They are both described in 
chapter 8.) In addition, subranges improve readability. Because a 
subrange defines the valid range of values for a variable, it is more 
meaningful to you for documentation and maintenance. 

The operations permitted on a subrange are the same as those 
permitted on its type (the type of its lower and upper bound). 

Example: 

This example shows the definition of a new type named LETTERS, 
which consists of the characters 'a' through 'z' only. It also defines an 
ordinal named COLORS, consisting of the colors listed. The variable 
declaration declares variable SCORES to consist of the numbers 
through 100. The lower and upper bounds are of integer type, so the 
subrange is also an integer type. STATUS is a subrange of boolean 
values, which could have been declared simply as BOOLEAN. HOT_ 
COLORS is a subrange of the ordinal type COLORS. It consists of the 
colors RED, ORANGE, and YELLOW. 

TYPE 

letters = 'a' . . 'z' , 

colors = (red, orange, yellow, white, green, blue); 

VAR 

scores: . . 100, 
Status: FALSE . . TRUE, 
hot_colors: red .. yellow; 
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Floating-Point Type 

The floating-point type defines real numbers. 

Real 

Use the keyword REAL to specify a real type. 

Real numbers range in value from 4.8 * 10**(-1234) to 5.2 * 
10**(1232). 

The operations permitted on real types are assignment, addition, 
subtraction, multiplication, division, and all relational operations. 

The functions $INTEGER and $REAL, described in chapter 6, convert 
between integer type and real type. 

Cell Type 

The cell type represents the smallest storage location that is directly 
addressable by a pointer. On NOS/VE, a cell is an 8-bit byte within a 
64-bit memory word. 

Use the keyword CELL to specify a cell type. 

Operations permitted on a cell type are assignment and comparison 
for equality and inequality. 

Pointer Types 

A pointer represents the location of a value rather than the value 
itself. When you reference a pointer, you indirectly reference the 
object to which it is pointing. 

Use this format to specify a pointer type: 

* type 

type 

Type to which the pointer can point. It can be any defined 
type. With the exception of a pointer to cell type (discussed 
later in this chapter), the pointer can point only to objects of 
the type specified. 
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Pointer 



ror example, 

VAR 

integer_po inter: "integer; 

defines a pointer named INTEGER. POINTER that can point only to 
integers. 



INTEGER POIMTER- 



any 
integer 



INTEG: 86/02/24 

Use this format to specify the object of a pointer (that is, what the 

pointer points to): 

pointer_name " 

pointer _ name 

The name you gave the pointer in the variable declaration. 

This preceding notation is called a pointer reference; it refers to the 
object to which pointer_name points. It can also be referred to as a 
dereference. For example, 

integer_pointer" 

identifies a location in memory; it is the location to which 
INTEGER_POINTER points. 

INTEGER POINTER ~ 

INTEGER POINTER — — > 



any 
integer 



POINT: 86/02/24 

You can initialize or assign a value to the object of a pointer as you 

would any other variable; that is: 

pointer _ name * := value; 
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Pointer 

This assigns the specified value to the object that the pointer points 
to. For example, 

integer .pointer* := 5; 

assigns the integer value 5 to the location that INTEGER_POINTER 
points to: 



INTEGER POINTER 



INTEGER_POINTER 

-+ 5 



INTEG5: 86/02/24 

You can assign the object of a pointer to a variable in the same way: 

variable := pointer _ name *; 

This takes the value of what pointer _ name points to and assigns it to 
the variable. For example, 

i := integer_pointer~; 

assigns to I the contents of what INTEGER_ POINTER points to, that 
is, 5. 

If a pointer reference is to another pointer type variable, meaning 
that the pointer points to a pointer that in turn points to a variable, 
you can specify the variable in the format: 

pointer _ name ** 

For example, the declarations 

TYPE 

integer_pointer = 'integer; 



VAR 

pointer_2: *integer_pointer; 

can be pictured as follows: 

POINTER_2 " 
POINTER 2 



POINTER 2~~ 



a pointer 
INTEGER POINTER 



any 

integer 



P0INT2: 86/02/24 



4-14 CYBIL Language Definition Revision F 

W | 01/22/87 19:59:24 | 02/13/87 09:46:31 | 87/03/25 22.17.32 | 60464113 F | TYPES | DRAFT COPY 



Pointer 



■»nT"iTmTTiTi £\ __ "_- i. -_ j_ _ _ ___*.. j. _ _.■**. T~a T;iii.iri -n tv i-»*— i y-r. T-rriT~v 



r-\_>ii>irjn,_i points to a pointer 01 type ii\i.Ejijiin,_ruirNTJi.K. 
INTEGER_POINTER points to integers. A reference to POINTER_2 
refers to the location of the pointer that in turn points to an integer. 
A reference to POINTER_2 AA refers to the location of the integer. 

A pointer can be assigned any of the following values: 

• The pointer constant NIL. NIL is the value of a pointer variable 
without an object; the variable is not currently assigned to any 
location. It can be assigned to or compared with any pointer of 
any type. 



• 



The pointer symbol * followed by a variable of the type to which 
the pointer can point. If the variable is a formal value parameter, 
the pointer cannot be used to modify the variable. 

A pointer variable, which can be a component of a structured type 
as well as a valid parameter in a function. 

A function that returns a pointer as a value (such as the #LOC, 
#PTR, #REL, and #SEQ functions described in chapter 6). 
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Pointers allow you to manipulate storage dynamically. Using pointers, 
you can create and destroy variables while a program is executing. 
Memory is allocated when the variable is created and released when 
it is destroyed. Pointers also allow you to reference the variables 
without giving each a unique name. 

Static pointers cannot point to value parameters or stack variables. * 
Stack pointers cannot point to value parameters or higher level stack 
variables. The lifetime of the pointer must be greater than or equal to 
the lifetime of the data. Parameter list pointers cannot point to value 
parameters or stack variables at the same or a higher level. 

Permissible operations on pointers are assignment and comparison for 
equality and inequality. 

Pointers to adaptable types (adaptable strings, arrays, records, 
sequences, and heaps) provide the only method for accessing objects of 
these types other than through formal parameters of a procedure. 
Specifically, pointers to adaptable types and pointers to bound variant 
records are used to access adaptable variables and bound variant 
records whose types have been fixed by an ALLOCATE, PUSH, or 
NEXT statement (described in chapter 5). 

Pointers are equivalent if they are defined in terms of equivalent 
types. A pointer to a fixed type (as opposed to an adaptable type) can 
be assigned and compared to a pointer to an adaptable type or bound 
variant record if the adaptable type is potentially equivalent to the 
fixed type. (Refer to Equivalent Types earlier in this chapter for 
further information on potentially equivalent types.) 



1. For further information on the run- time stack, refer to appendix F, The CYBIL 
Run-Time Environment. 
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Pointer 



lixampie: 

The following example shows the declaration and manipulation of two 
pointer type variables. Comments appear to the right. 



TYPE 

ptr = "integer; 

VAR 



PTR can contain pointers to integers. 



j, 




k:i 


nteger, 


pi: 


Ptr, 


P2: 


"Pi, 



PI can contain pointers to integers. 

P2 can contain pointers to PI (that is, 
pointers that point to pointers to integers). 
It could have been written as P2: *" 
INTEGER. 



b2: boolean; 



ALLOCATE p1 ; 

ALLOCATE p2 ; 

p1" := 10; 
p2" := p1; 

j := Pi*; 

k := p2""; 



b1 



k; 



Allocates space for an integer (because that 
is what PI points to) and sets PI to point 
to that space. 

Allocates space for a pointer that points to 
an integer and sets P2 to point to that 
pointer. 

The space pointed to by PI is set to 10. 

The space pointed to by P2 is set to the 
value of the pointer PI. 

J is set to what PI points to: the integer 
10. 

K is set to the object of the pointer that 
P2 points to. (Think of P2 A " as "P2 points 
to a pointer; that pointer points to an 
object." You are assigning that object to 
K.) P2 points to PI, which points to the 
integer 10. 

J and K are both 10. Bl is TRUE. 
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Pointer to Cell 



b2 := p1' 



P2" 



P1 := NIL; 
k := p1"; 



IF p2 = NIL THEN 

k := k + 1; 
I FEND; 

P1 := "(i + j + 2 * k); 



PI points to an integer. P2 points to the 
pointer (PI) that points to the same 
integer. Their values are the same and B2 
is TRUE. 

PI no longer points to anything. 

The statement is in error because PI does 
not point to anything. 

A valid statement. K is not incremented 
because P2 still points to PI. 



An invalid statement. The location of an 
expression cannot be found. 



Pointer to Cell 

A pointer to cell type can take on values of any type. 

Use this format to declare a pointer to a cell: 

-CELL 

A variable declared simply as a pointer type variable can take on as 
values only pointers to a single type, which is specified in the 
pointer's declaration. A variable declared as a pointer to cell variable 
has no such restrictions. It can take on values of any type. Also, any 
fixed or bound variant pointer variable can assume a value of pointer 



Permissible operations on a pointer to a cell are assignment and 
comparison for equality and inequality. In addition, a pointer to a cell 
can be assigned to any pointer to a fixed or bound variant type. But 
the pointer to the fixed or bound variant type cannot have as its 
value a pointer to a variable that is not a cell type or, furthermore, 
whose type is not equivalent to the type to which the target of the 
assignment points. A pointer to a cell can be the target of assignment 
of any pointer to a fixed or bound variant type. 
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Relative Pointer 



iteiauve f-oinier 

Relative pointer types represent relative locations of components 
within an object with respect to the beginning of the object. 

Use this format to specify a relative pointer: 

REL { (parent _name) } "component _ type 

parent _name 

Name of the variable that contains the components being 
designated by relative pointers. Specify a string, array, record, 
heap, or sequence type (either fixed or adaptable). If it is 
omitted, the default heap is used. 

component _ type 

Type of the component to which the relative pointer will point. 

Relative pointers are generated using the standard function #REL 
(described in chapter 6). A relative pointer cannot be used to access 
data directly. Instead, the relative pointer must be converted to a 
direct pointer using the standard function #PTR (also described in 
chapter 6). The direct pointer can then be used to access the data. 

Relative pointers have three major differences from the other pointers 
discussed in this chapter: 

• Relative pointers may need less space than other pointers. 

• A linked list or array of relative pointers (or some similar 
organization) within a parent type variable is still correct if the 
entire variable is assigned to another variable of the same parent 
type. 

• Relative pointers are independent of the base address of the parent 
type variable. 

Operations permitted on a relative pointer are assignment, comparison 
for equality and inequality, and the #PTR function. Relative pointers 
can be assigned and compared if they are of equivalent relative 
pointer types. Relative pointer types are equivalent if they are defined 
in terms of equivalent parent types and equivalent component types. 



Revision F Types 4-19 



Structured Types 

Structured Types 

Structured types are combinations of the basic types already described 
in this chapter (integer, character, boolean, ordinal, subrange, real, 
cell, and pointer). Even the structured types discussed here can be 
combined with each other but they are still essentially groups of the 
basic types. The structured types described in this section are: 

• Strings 

• Arrays 

• Records 

• Sets 

Strings 

A string is one or more characters that can be identified and 
referenced as a whole by one name. 

Use this format to specify a string type: 

STRING (length) 

length 

A positive integer constant expression from 1 to 65,535. 

If you specify an initial value in the variable declaration for a string, 
it can be: 

• A string constant 

• The name of a string constant declared with a constant declaration 

• A constant expression (as described in chapter 2) 

A string cannot be packed. 2 Two string types are equivalent if they 
have the same length. 



2. Packing is a characteristic of arrays and records. When an array or record is 
declared as being packed, its components are mapped in storage to conserve storage 
space; otherwise, components are mapped to optimize access time. 
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Strings 



rne operations permitted on string types are assignment ana 
comparison (all six relational operations). For further information, 
refer to Assigning and Comparing String Elements later in this 
chapter. 

Substrings 

You can reference a part of a string (called a substring) or a single 
character of a string. 

Use this format to reference a substring or single character: 

name (position {, length} ) 

name 

Name of the string. 

position 

Position within the string of the first character of the 
substring. (The position of the first character of the string is 

a1*xTOij-e 1 "^ slrtga/vi-ftr o -rwiei^iTTfi l'M^-oQKiT flvnrpeoinn lace f non r»r* 

equal to the length of the string plus one; that is, 

1 ^ position ^ string length + 1 

If you specify string length plus one, the substring is an empty 
string. 

length 

Number of characters in the substring. Specify a nonnegative 
integer expression or * (the asterisk character). If you specify 
*, the substring consists of the character specified by the 
position parameter and all characters following it in the string. 
If you specify 0, the substring is an empty string. Omission 
causes 1 to be used. 
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A substring reference in the form 

name(position) 

is a substring of length 1, a single character. In this form, it can be 
used anywhere a character expression is allowed. It can be: 

• Compared with a character 

• Tested for membership in a set of characters 

• Used as the initial and/or final value in a FOR statement that is 
controlled by a character variable 

• Used as a value in a CASE statement 

• Used as an argument in the standard functions $INTEGER, SUCC, 
and PRED 

• Assigned to a character variable 

• Used as an actual parameter to a formal parameter of type 
character 

• Used as an index value corresponding to a character type index in 
an array 

A string constant, even if it is declared with a name in a constant 
(CONST) declaration, is not a variable. Therefore, substrings cannot 
be referenced in a string constant. 
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Strings 

Examples: 

If a string variable LETTERS is declared and initialized as follows 

VAR 

letters: [STATIC] string (6) := 'abcdef' ; 

the following substring references are valid: 

Substring Comments 

LETTERS(l) Refers to 'a'. 

LETTERS(6) Refers to T. 

LETTERS(1,6) Refers to the entire string. 

LETTERSd,*) Refers to the entire string. 

LETTERS(2,5) Refers to 'bcdef . 

LETTERS(2,*) Refers to 'bcdef. 

LETTERS(2,0) Refers to an empty string ' '. 

LETTERS(7,*) Refers to an empty string ' '. 

LETT'ERS(O), LETTERS(8), and LETTERS(8,0) are illegal. 
If a pointer variable is declared and initialized as follows 

VAR 

string_ptr: [STATIC] "string (6) := "letters; 

then STRING_PTR points to the string LETTERS and the pointer 
variable STRING_PTR* can be used to make substring references 
similar to the variable LETTERS. 

Substring Comments 

STRING_PTR"(1) Refers to 'a'. 

STRING_PTR*(6) Refers to 'f . 

STRING_PTR"(1,6) Refers to the entire string. 

STRING_PTR A (2,*) Refers to 'bcdef. 

STRING_PTR*(2,0) Refers to an empty string ' '. 
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Assigning and Comparing String Elements 

You can assign or compare a character, substring, or string to a 
substring, string variable, or character variable. A character is treated 
as a string of length 1. You must specify the substring reference 
when assigning a character variable to a string. 

If you assign a value that is longer than the substring or variable to 
which it is being assigned, the value is truncated on the right. If you 
assign a value that is shorter, spaces are added on the right to fill 
the field. This method is also used for comparing strings of different 

lengths. 

If you assign a substring to a substring of the same variable, the 
fields cannot overlap or the results are undefined. 

The concatenation operation CAT cannot be used with string variables. 

Example: 

Assume the string variable DAY is declared and initialized as follows: 

VAR 

day: [STATIC] string (6) := 'monday' ; 

The following assignments can be made: 

short := day (1, 3); 
empty := day (1, 0); 

SHORT is assigned the string 'mon'. EMPTY is assigned a null string. 
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Arrays 

An array in CYBIL is a collection of data of the same type. You can 
access an array as a whole, using a single name, or you can access 
its elements individually. 

Use this format to specify an array type: 

{PACKED} ARRAY [subscript .bounds] OF type 

PACKED 

Optional packing parameter. When it is specified, the elements 
of the array are mapped in storage in a manner that conserves 
storage space, possibly at the expense of access time. If it is 
omitted, the array is unpacked; that is, the elements are 
mapped in storage to optimize access time rather than to 
conserve space. (The array itself is always mapped into an 
addressable memory location; that is, it starts on a word 
boundary or, in the case of a packed array in a record, on a 
byte boundary.) For further information on how data is stored 
in memory, refer to appendix E, Data Representation in 
Memory. 

If the array contains structured types (such as records), the 
elements of that type (the fields in the records) are not 
automatically packed. The structured type itself must be 
declared packed. 

subscript _ bounds 

Specifies the size of the array and what values you can use to 
refer to individual elements. Bounds can be any scalar type or 
subrange of a scalar type, and is often a subrange of integers. 

type 

Type of the elements within the array. The type can be any 
defined type, including another array, except an adaptable type 
(that is, an adaptable string, array, or record). All elements 
must be of the same type. 
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Elements of a packed array cannot be passed as reference (that is, 
VAR) parameters in programs, functions, or procedures. 

Two array types are equivalent if they have the same packing 
attribute, equivalent subscript bounds, and equivalent component 

types. 

The only operation permitted on an array type is assignment. 

Initializing Elements 

An array can be initialized using an indefinite value constructor. An 
indefinite value constuctor is a list of values assigned in order to the 
elements of an array. The first value in the list is assigned to the 
first element, and so on. The number of values in the value 
constructor must be the same as the number of elements in the array. 
The type of the values must match the type of the elements in the 
array. An indefinite value constructor has the form 

[value {,value}...] 

where value can be one of the following: 

• A constant expression 

• Another value constructor (that is, another list) 

• The phrase 

REP number OF value 

which indicates the specified value is repeated the specified 
number of times 

• The asterisk character (*), which indicates the element in the 
corresponding position is uninitialized 

An indefinite value constructor can be used only for initialization; it 
cannot be used to assign values during program execution. Individual 
elements can be assigned during execution using the assignment 
statement (described in chapter 5). 
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Arrays 



xtvpxox c;xxx;xxxg xjxcixxxcxxio 

The array name alone refers to the entire structure. 
Use this format to refer to an individual element of an array: 
array _ name[suhscript] 

subscript 

A scalar expression within the range and of the type specified 
in the subscript_bounds field of the array declaration. This 
subscript specifies a particular element. 

Examples: 

xiiio cAaiupic aiiuvvo bix^: uGxxxxxbxUix wx a ujtl/c naiucu x uu_ xxu/ijij} 

which is an array of 10 elements that can take on the values defined 
in POSITION. The variable declaration declares variable NUMBERS 
to be an array of five elements initialized to the values 1, 2, 3, 4, and 
5 where 1 is the value of the first element, and so on. LETTERS is 
an array of 26 elements that can be any characters. BIG_ TABLE is a 

TYPE 

position = (boi, asis, eoi), 

pos_table = array [1 .. 10] of position; 

VAR 

i: [STATIC] integer := 5, 

numbers: [STATIC] array [1 . . 5] of integer := [1, 2, 3, 4, 5],. 

letters: array ['a' .. 'z'] of char, 

big.table: array [1 .. 100] of pos_table; 

The declaration of BIG_ TABLE is equivalent to: 

VAR 

big_table: array [1 .. 100] of array [1 .. 10] of position; 
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You can reference individual elements using the following statements. 

numbers [i] Refers to the fifth element of the 

array NUMBERS (similar to 
NUMBERS [5]). 

letters t'b'] := 'B' ; Sets the second element of the array 

LETTERS to the uppercase character 
B. 

big_table [13] [10] := asis; Sets the tenth element of the 

thirteenth array to ASIS. 

The following example shows the declaration and initialization of a 
two-dimensional array named DATA_ TABLE. All the components of 
the third element of the array (which is an array itself) are set to 0. 
Notice that the third element of the last array, DATA_TABLE [4][3], 
is uninitialized. 

TYPE 

innerarray = array [1 ..5] of integer, 
twodim = array [1 ..4] of innerarray; 

VAR 

data_table: [STATIC] twodim := [[5, - 10, 2, 6, 3], 

[4, 11, 19, - 3, 6], 
[REP 5 of 0], 
[3, - 9, * , 4, 15]]; 



The following example demonstrates how a string can be passed to an 

VAR 

output_l ine: string (80), 
output_array: array [1..80] of char, 
i: integer; 

FOR i := 1 to 80 DO 

output_array [i] := output_line (i); 
FOREND; 
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neeoras 

Records are collections of data that can be of different types. You can 
access a record as a whole using a single name, or you can access 
elements individually. 

A record has a fixed number of components, usually called fields, each 
with its own unique name. Different fields are used to indicate 
different data types or purposes. 

There are two types of records: invariant records and variant records. 
Invariant records consist of fields that don't change in size or type. 
Variant records can contain fields that vary depending on the value of 
a key variable. Formats used for specifying both kinds of records are 
given later in this chapter. 

Operations permitted on record types are assignment and, for 
invariant records only, comparison for equality and inequality. The 
invariant records being compared cannot contain arrays as fields. 
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Invariant Records 

An invariant record consists of fields that do not vary in size or type 
once they have been declared. They are called fixed or invariant 
fields. 

Use this format to specify an invariant record: 

{PACKED} RECORD 

field .name : {ALIGNED {[offset MOD base]}} type 
{field _name : {ALIGNED {[offset MOD base]}} type}... 

RECEND 

PACKED 

Optional packing parameter. When it is specified, the fields of 
a record are mapped in storage in a manner that conserves 
storage space, possibly at the expense of access time. If it is 
omitted, the record is unpacked; that is, the fields are mapped 
in storage to optimize access time rather than to conserve 
space. For further information on how data is stored in 
memory, refer to appendix E, Data Representation in Memory. 

If one of the fields is a structured type (such as another 
record), the elements of that type are not packed automatically. 
The structured type itself must be declared packed. 

field _ name 

Name identifying a particular field. The name must be unique 
within the record. Outside of the record declaration, it can be 
redefined. 



Optional alignment parameter. If specified, it can appear alone 
or with an offset, in the form: 

ALIGNED [offset MOD base] 

When a field is aligned, it is mapped in storage so that it is 
directly addressable. This means the field begins on an 
addressable boundary to facilitate rapid access to the field. This 
may negate some of the effect of packing the record. For 
further information, refer to Alignment later in this chapter. 
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1 M-S\Y\ 



Offset mvu oase 

Optional offset to be used in conjunction with the ALIGNED 
parameter. This offset causes the field to be mapped to a 
particular hardware address relative to the specified base and 
offset. Specify a particular word or byte within a word. Base is 

o v aiuovvu xxx ai> u\j xxxxu. LaaC Vitui \x iJuuiiUCLx jr } unoCv 10 bxiCxx 

evaluated to determine the number of bytes offset within that 
word. Filler is created if necessary to ensure that the field 
begins on the specified word or byte. 

offset 

Byte offset within the word specified by base. Specify an 
integer constant less than base. 



Word boundary. Specify an integer constant that is divisible 
by 8. For automatic variables, the base can only be 8. 

type 

Any defined type, including another record, other than an 
adaptable type. 

Elements of a packed record cannot be passed as reference (that is, 
VAR) parameters in programs, functions, or procedures unless they are 
aligned. 

The only operations possible on whole invariant records are 
assignment and comparison. A record can be assigned to another 
record if they are both of the same type. A record can also be 
compared to another record for equality or inequality if they are both 
of the same type. Invariant record types are the same if they have 
the same packing attributes, the same number of fields, and 
corresponding fields have the same field names, same alignment 
attribute, and equivalent types. 
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Example: 

This example shows the definition of two new types, both records. The 
record named DATE has three fields that can hold, respectively, DAY, 
MONTH, and YEAR. The record named RECEIPTS appears to contain 
two fields, NAME and PAYMENT; but PAYMENT is itself a record 
consisting of the three fields in DATE, just described. Initialization of 
fields within records is discussed under Initializing Elements later in 
this chapter. 

TYPE 

date = record 

day: 1 . . 31, 

month: string (4), 

year: 1900 ..2100, 
recend , 
receipts = record 

name: string (40), 

payment: date, 
recend ; 
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A variant record contains fields that may vary in size, type, or 
number depending on the value of an optional tag field. These 
different fields are called variant fields or variants. 

Use this format to specify a variant record: 

{PACKED} {BOUND} RECORD 

{fixed_field_name : {ALIGNED {[offset MOD base]}} type}... 3 
CASE {tag_field_name : } tag _ field, type OF 
= tag _ field _ value = 

variant _ field 
{= tag_field_value = 

variant _ field}. . . 
CASEND 
RECEND 

PACKED 

Optional packing parameter. When it is specified, the fields of 
a record are mapped in storage in a manner that conserves 
storage space, possibly at the expense of access time. If it is 
omitted, the record is unpacked; that is, the fields are mapped 
in storage to optimize access time rather than to conserve 
space. For further information on how data is stored in 
memory, refer to appendix E, Data Representation in Memory. 

If a field is a structured type (such as another record), the 
elements of that type are not packed automatically. The 
structured type itself must be declared packed. 

BOUND 

Optional parameter indicating that this is a bound variant 
record. If specified, the tag_field_name parameter is required. 
Additional information on bound variant records follows the 
parameter descriptions. 



3. When you specify more than one fixed field, you must separate them with commas. 
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fixed_field_ name 

Name of a fixed field (one that does not vary in size), as 
described under Invariant Records earlier in this chapter. The 
name must be unique within the record. Outside of the record 
declaration, it can be redefined. There can be zero or more 
fixed fields. 

ALIGNED 

Optional alignment parameter; the same as that for an 
invariant record. If specified, it can appear alone or with an 
offset in the form: 

ALIGNED [offset MOD base] 

When a field is aligned, it is mapped in storage so that it is 
directly addressable. This means the field begins on an 
addressable boundary to facilitate rapid access to the field. This 
may negate some of the effect of packing the record. For 
further information, refer to Alignment later in this chapter. 

offset MOD base 

Optional offset to be used in conjunction with the ALIGNED 
parameter, the same as that for an invariant record. This offset 
causes the field to be mapped to a particular hardware address 
relative to the specified base and offset. Specify a particular 
word or byte within a word. Base is evaluated first to find the 
word boundary; offset is then evaluated to determine the 
number of bytes offset within that word. Filler is created if 
necessary to ensure that the field begins on the specified word 
or byte. 

offset 

Byte offset within the word specified by base. Specify an 
integer constant less than base. 

base 

Word boundary. Specify an integer constant that is divisible 
by 8. For automatic variables, the base can only be 8. 

type 

Any defined type, including another record, other than an 
adaptable type. 
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Optional parameter specifying the name of the variable that 
determines the variant. The current value of this variable 
determines which of the variant fields that follow will actually 
be used. If it is omitted, the variant that had the last 
assignment maae vo one 01 IIS ileitis is tissu. InlS pjursiiiieMsr is 
required if the record is a bound variant record (BOUND is 
specified). Additional information is given following the 
parameter descriptions. 

tag_field_type 

Any scalar type. This type defines the values that the tag_ 
field_ value can have. 

tag_field _ value 

Constant scalar expression or subrange. Specify one of the 
possible values that can be assigned to the variable specified 
by tag_field_name. It must be of the type and within the 
range specified by tag_field_type. Specifying a subrange has 
the same effect as listing each value separately. 

variant _ field 

Zero or more fixed fields of the same form as that shown in 
the second line of this format. This field exists only if the 
current value of tag_field_name is the same as that in the 
tag_field_ value associated with the variant_field. The last 
field can be a variant itself. 

The variant fields must follow all invariant (fixed) fields in the 
record. The field following the reserved word CASE is called the tag_ 
field_name. The tag_field_name can take on different values during 
execution. When its value matches one of the values specified in a 
tag_field_ value, the variants associated with that tag_field_ value 
are used. Variants themselves consist of zero or more fixed fields 
optionally followed by another variant. If the last field is itself a 
variant, it can have another CASE clause, tag_field_name, and so on. 

The tag_field_name is an optional field. When it is omitted, no 
storage is assigned for the tag field. If the record has no tag field, 
you choose a variant by making an assignment to a subfield within a 
variant. The variant containing that subfield becomes the currently 
active variant. In a variant record without a tag field, all fields in a 
new active variant become undefined except the subfield that was just 
assigned. An attempt to access a variant field that is not currently 
active produces undefined results. 
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Space for a variant record is allocated using the largest possible 
variant. 

Variant record types are equivalent if they have the same packing 
attribute, their fixed fields are equivalent (as defined for invariant 
record types), they have the same tag field names, their tag field 
types are equivalent, their tag field values are the same, and their 
corresponding variant fields are equivalent. 

A bound variant record is specified by including the BOUND 
parameter; the tag_field_name is also required. A bound variant 
record type can be used only to define pointers for bound variant 
record types (that is, bound variant pointers). A variable of this type 
is always allocated in a sequence or heap, or in the run-time stack 
managed by the system. 

When allocating a bound variant record, you must specify the tag 
field values that select the variation of the record. Only the specified 
space is allocated. The ALLOCATE statement in this case returns a 
bound variant pointer. 

If a formal parameter of a procedure is a variant record type, the 
actual parameter cannot be a bound variant record type. 

A record cannot be assigned to a variable that is a bound variant 
record type. 

Bound variant record types are equivalent if they are defined in terms 
of equivalent, unbound records. A bound variant record type is never 
equivalent to a variant record type. 
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This example defines a type named SHAPE, which becomes the type 
of the tag field, in this case a variable named S. When S is equal to 
TRIANGLE, the record containing fields SIZE, INCLINATION, 
ANGLE1, and ANGLE2 is used as if it were the only record 
available. When the value of S changes, the record variant being used 
also changes. 

TYPE 

shape = (triangle, rectangle, circle), 
angle = - 180 . . 180, 
figure = record 
x, 

y, 

area: real, 
case s: shape of 
= triangle = 

si 28: real, 

inclination, 

anglel, 

angles : angle, 
= rectangle = 

sidel , 

side2: integer, 

skew, 

angle3: angle, 
= circle = 

diameter: integer, 
casend , 
recend; 
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Initializing Elements 

A record can be initialized using an indefinite value constructor. An 
indefinite value constructor is a list of values assigned in order to the 
fields of a record. The first value in the list is assigned to the first 
field, or first element in a field, and so on. The type of the values 
must match the type of the elements in the field. An indefinite value 
constructor has the form 

[value {,value}..."i 

where value can be one of the following: 

• A constant expression 

• Another value constructor (that is, another list) 

• The asterisk character (*), which indicates the element in the 
corresponding position is uninitialized 

An indefinite value constructor can be used only for initialization; it 
cannot be used to assign values during program execution. Individual 
fields can be assigned during execution using the assignment 
statement (described in chapter 5). 

Example: 

The variable BIRTH _ DAY, in this example, is a record with the 
fields described in the record type named DATE. It is initialized using 
an indefinite value constructor to the 24th day of August, 1950. 



TYPE 








date = 


record 






day: 


1 .. 31, 






month: string 


(4), 




year : 


I3UU . . 


n inn 

d. iuu 


, 


recend; 








VAR 








birth.day: [STATIC] 


date 



[24, 'aug', 1950]; 
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The record name alone refers to the entire structure. 
Use this format to access a field in a record: 

record _ name.neld _ name {.sub — fieid_ name}. . . 

record _ name 

Name of the record as declared in the variable declaration. 

field _ name 

Name of the field to be accessed. If the field is an array, a 
reference to an individual element can also be included using 
the form: 

field _name[subscript] 

sub_field_ name 

Optional field name. Use this parameter if the field previously 
specified is itself a structured type, for example, another 
record. If the contained field is an array, you can include a 
reference to an individual element in the format: 

sub_field_ name[subscript] 

Example: 

The variable PROFILE is a record with the fields described in the 
record type STATS. In this example, PROFILE is initialized with the 
values in the indefinite value constructor in the variable declaration. 



TYPE 




stats = record 


age: 6 


. . 66, 


married 


: boolean, 


date: record 


day: 


1 .. 31, 


month 


: 1 .. 12, 


year .- 


80 .. 90, 


recend , 




recend; 




VAR 




prof i le: 


[STATIC] S 



[3, 5, 82]]; 
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The following references can be made to fields: 
Field Content 



prof i le.age 


23 


profi le. married 


FALSE 


profi le. date. day 


3 


profile. date. month 


5 


profi le. date. year 


82 


Alignment 





Unpacked records and their fields are always aligned (that is, directly 
addressable). Even if it is packed, a record is always aligned (that is, 
the first field is directly addressable) unless it is an unaligned field 
within another packed structure. Fields in a packed record, however, 
are not aligned unless the ALIGNED attribute is explicitly included. 
Aligning the first field of a record aligns the entire record. 

Unpacked records and their fields, because they are aligned, can 
always be passed as reference (that is, VAR) parameters in programs, 
functions, and procedures. Packed records must be aligned to be valid 
as reference parameters. Packed, unaligned records cannot be used. 
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Sets 

A set is a collection of elements that, unlike arrays and records, is 
always operated on as a single unit. Individual elements are never 
referenced. 

Use this format to specify a set type: 

SET OF scalar_type 

scalar _ type 

Type of all the elements that will be within the set. Specify a 
scalar type or a subrange of a scalar type. The maximum 
number of elements in a set is 32,767. 

All members of a set must be of the same type. Members within a set 
have no specific order; that is, order has no effect in any of the 
operations performed on sets. 

Set types are equivalent if their elements have equivalent types. 

Operations allowed on sets are assignment, intersection, union, 
difference, symmetric difference, negation, inclusion, identity, and 
membership. Refer to Operators in chapter 5 for further information 
on set operations. The SUCC and PRED functions are not defined for 

set types. 

The difference (-) or symmetric difference (XOR) of two identical sets 
is the empty set. The empty set is contained in any set. For a given 
set, the complement of the empty set, -[ ], is the full set. 
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Initializing and Assigning Elements 

Values can be assigned to a set using an indefinite value constructor 
or a set value constructor. An indefinite value constructor can be used 
only for initialization; a set value constructor can be used for both 
initialization and assignment during program execution. 

An indefinite value constructor is a list of values assigned to the set. 
The type of the values must match the type of the set. 

Use this format to specify an indefinite value constructor: 

[value {,value}...] 

value 

Constant expression or another indefinite value constructor 
(that is, another list). 

A set value constructor constructs a set through explicit assignment. 
Use this format to specify a set value constructor: 

$name [ { value lvalue}...} ] 

name 

Name of the set type. The dollar sign ($) must precede the 
name to indicate a set value constructor. 

value 

Expression of the same type as that specified for the set. When 
used in initialization, only constants or constant expressions are 
valid. The empty set can be specified by [ ]. 

A set value constructor can be used wherever an expression can be 
used. 
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example: 

This example shows the declaration of a variable named ODD, which 
is a type of a set of integers from to 10. It is initialized with an 
indefinite value constructor assigning the integers 1, 3, and 5 to the 
set. The variable VOWELS is a set that can contain any of the letters 
'a' through 'z\ It is assigned the letters 'a', 'e', T, 'o' and 'u' using a 
set value constructor. It constructs a set of type C, which contains the 
specified letters; then that set is assigned to the set VOWELS. The 
variables LIST_1 and LIST_2 are sets that can contain any 
characters. LIST_1 is assigned, using a set value constructor, the 
letters 'x', 'y', and 'z\ LIST_2 is assigned the complement of 'x', y', 
and 'z', that is, a set consisting of every character except the letters 
'x', 'y', and V. 

TYPE 

a = set of . . 10, 
c = set of 'a' . . 'z', 
ch = set of char; 

VAR 

odd: [STATIC] a := [1, 3, 5], 

vowels: c, 

llst.l, 

liSt_2: Ch; 



vowels 
list_1 
list_2 



= $c ['a', 'e', '1', 'o', 'u']; 
= $ch ['x', 'y', 'z']; 
= - $ch ['x', 'y', 'z'] ; 
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Storage Types 

Storage types represent structures to which variables can be added, 
deleted, and referenced under program control. (The statements used 
to access the storage types are described under Storage Management 
Statements in chapter 5.) There are two storage types: 

• Sequences 

• Heaps 

Sequences 

A sequence type is a storage structure whose components are 
referenced sequentially using pointers. It can be pictured as follows: 



Pointer to the first component 



SEQNCE: 86/08/08 

These pointers are constructed using the RESET and NEXT 
statements (described in chapter 5). The RESET statement moves the 
pointer to the beginning of the sequence or to a specific variable 
within the sequence. The NEXT statement moves the pointer to the 
next available space. 
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Use this format to specify a sequence type: 

SEQ ({REP number OF} type {,{REP number OF} type}...) 

number 

Positive integer constant expression. This is an optional 
parameter specifying the number of repetitions of the specified 
type. 

type 

Fixed type that can be a user-defined type name; one of the 
predefined types integer, character, boolean, real, or cell; or a 
structured type using the preceding types. 

You can repeat the phrase REP number OF type as many times as 
desired. It specifies that storage must be available to hold the 
indicated number of occurrences of the named types simultaneously. 
The types that are actually stored in a sequence do not have to be 
the same as the types specified in the declaration, but adequate space 
must have been allocated to hold those types in the declaration. In 
other words, if a sequence is declared with several repetitions of 
integer type, the space to hold these integers has to be available, but 
it might actually hold strings or boolean values. 

Sequence types are equivalent if they have the same number of REP 
phrases and corresponding phrases are equivalent. Two REP phrases 
are equivalent if they have the same number of repetitions of 
equivalent types. 

Assignment to another sequence is the only operation permitted on 
sequences. 
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Heaps 

A heap type is a storage structure whose components are referenced 
using pointers but, unlike a sequence, they are not allocated and 
referenced sequentially. A heap can be pictured as follows: 




Pointer to a 
component 



HEAP : 8 6/08/08 

The components of a heap are allocated explicitly using the 

ALLOCATE statement, which also constructs pointers that you can 

use to reference the components. The components of a heap are 

released using the FREE and RESET statements (described in chapter 

5). 
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use tnis tormat to speerry a neap type: 

HEAP ({REP number OF} type {,{REP number OF} type}...) 

number 

Positive integer constant expression. This is an optional 
parameter specifying the number of repetitions of the specified 
type. 

type 

Fixed type that can be a user-defined type name; one of the 
predefined types integer, character, boolean, real, or cell; or a 
structured type using the preceding types. 

You can repeat the phrase REP number OF type as many times as 
desired. It specifies that storage must be available to hold the 
indicated number of occurrences of the named types simultaneously. 
The types that are actually stored in a heap do not have to be the 
same as the types specified in the declaration, but adequate space 
must have been allocated to hold those types in the declaration. In 
other words, if a heap is declared with several repetitions of integer 
type, the space to hold these integers has to be available, but it might 
actually hold strings or boolean values. 

Heap types are equivalent if they have the same number of REP 
phrases and corresponding phrases are equivalent. Two REP phrases 
are equivalent if they have the same number of repetitions of 
equivalent types. 

J-liC GGI3.*XII> XlGuk/ twt-tXi. Kr\* Ill3.J-x3.g,\^VA VvXbOtJ. UliC i nil it HjiH I Pi ttJLxG ■ It-T'i i 

statements in the same way as a user-defined heap. For further 
information, refer to the descriptions of these statements in chapter 5. 



Revision F Types 4-47 



Adaptable Types 

Adaptable Types 

An adaptable type has indefinite size or bounds; it adapts to data of 
the same type but of different sizes and bounds. The types described 
thus far in this chapter are fixed types. An adaptable type differs 
from a fixed type in that the storage required for a fixed type is 
constant and can be determined before execution. Storage for an 
adaptable type is determined during program execution. 

An adaptable type can be a string, array, record, sequence, or heap 
and can define formal parameters in a procedure and adaptable 
pointers. Pointers are the mechanism used for referencing adaptable 
variables. 

The size of an adaptable type must be set during execution. This can 
be done in one of three ways: 

• If the adaptable type is a formal parameter to a procedure or 
function, the size is set by the actual parameters when the 
procedure or function is called. You can determine the length of an 
actual parameter string using the STRLENGTH function, and the 
bounds of an actual parameter array using the UPPERBOUND 
and LOWERBOUND functions. (For further information, refer to 
the description of the appropriate function in chapter 6.) 

• If the adaptable pointer type is on the left side of an assignment 
statement, the size is set by the assignment operation. It can be 
assigned any pointer whose current type is one of the types that 
the adaptable type can take on. 

• An adaptable type can also be set explicitly using the storage 
management statements (described in chapter 5). 

An adaptable type is declared with an asterisk taking the place of the 

CI7.0 nr nmin/lc nnrTnollr filling in fV»o i-xmc nr> iToripkla ^AAlnKafiAM 
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Adaptable Strings 

Use this format to specify an adaptable string: 
STRING ( * {<= length} ) 

length 

Optional parameter specifying the maximum length of the 
adaptable string. If it is omitted, 85,535 characters is assumed. 

If the string exceeds the maximum allowable length, an error occurs. 

Two adaptable string types are always equivalent. 

Adaptable Arrays 

Use this format to specify an adaptable array: 

{PACKED} ARRAY [flower _ bound ..} *] OF type 

PACKED 

Optional packing parameter. When it is specified, the elements 
of the array are mapped in storage in a manner that conserves 
storage space, possibly at the expense of access time. If it is 
omitted, the array is unpacked; that is, the elements are 
mapped in storage to optimize access time rather than to 
conserve space. (The array itself is always mapped into an 
addressable memory location.) For further information on how 
data is stored in memory, refer to appendix E, Data 
Representation in Memory. 

If the array contains structured types (such as records), the 
elements of that type (the fields in the records) are not 
automatically packed. The structured type itself must be 
declared packed. 
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lower _bound 

Constant integer expression that specifies the lower bound of 
the adaptable array. This parameter is optional, but its use is 
encouraged. Omission of this parameter (only the * appears) 
indicates it is an adaptable bound of type integer. 

type 

Type of the elements within the array. The type can be any 
defined type other then adaptable (that is, an adaptable string, 
array, record, sequence, or heap). All elements must be of the 
same type. 

Only one dimension can be adaptable in an array and that dimension 
must be outermost (first one in the declaration). 

Adaptable arrays adapt to a specific range of subscripts. An adaptable 
array can adapt to any array with the same packing attribute, 
equivalent subscript bounds, and equivalent component types. If a 
lower bound is specified in the adaptable array declaration, both 
arrays must also have the same lower bound. 

Adaptable array types are equivalent if they have the same packing 
attributes and equivalent component types, and if their corresponding 
array and component subscript bounds are equivalent. Two subscript 
bounds that contain asterisks only are always equivalent. Two 
subscript bounds that contain identical lower bounds are equivalent. 
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An adaptable record contains zero or more fixed fields followed by one 
adaptable field that is of an adaptable type. 

Use this format to specify an adaptable record: 

{PACKED} RECORD 

{fixed_field_name : {ALIGNED {[offset MOD base]}} type}...* 
adaptable _field_name : {ALIGNED {[offset MOD base]}} 
adaptable _ type 

RECEND 

PACKED 

Optional packing parameter. When it is specified, the fields of 
a record are mapped in storage in a manner that conserves 
storage space, possibly at the expense of access time. If it is 
omitted, the record is unpacked; that is, the fields are mapped 
in storage to optimize access time rather than to conserve 
space. For further information on how data is stored in 
memory, refer to appendix E, Data Representation in Memory. 

If a field is a structured type (such as another record), the 
elements of that type are not packed automatically. The 
structured type itself must be declared packed. 

fixed_field_ name 

Name identifying a particular fixed field. The name must be 
unique within the record. 

ALIGNED 

Optional alignment parameter. If it is specified, it can appear 
alone, or with an offset in the form: 

ALIGNED [offset MOD base] 

When a field is aligned, it is mapped in storage so that it is 
directly addressable. This means the field begins on an 
addressable boundary to facilitate rapid access to the field. This 
may negate some of the effect of packing the record. For 
further information, refer to Alignment earlier in this chapter. 



4. If you specify more than one fixed (nonadaptable) field, you must separate them 
with commas. 
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[offset MOD base] 

Optional offset to be used in conjunction with the ALIGNED 
parameter. This offset causes the field to be mapped to a 
particular hardware address relative to the specified base and 
offset. Filler is created if necessary to ensure that the field 
begins on the specified addressable unit. 

offset 

An integer constant. Offset must be less than base. 

base 

An integer constant that must be divisible by 8. For 
automatic variables, the base can only be 8. 

type 

Any defined type, including another record, other than an 
adaptable type. 

adaptable _ field _ name 

Name identifying the adaptable field. 

adaptable _ type 

An adaptable type. 

An adaptable record can adapt to any record whose types are the 
same except for the last field. That last field must be one to which 
the adaptable field can adapt. 



Two adaptable record types are equivalent if they have the same 

|/aviuiig oiuiuureo, uic same oiigiiuicut, tuc same uumuci ui neius, 

and corresponding fields with identical names and equivalent types. 
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Adaptable Sequences 

Use this format to specify an adaptable sequence: 

SEQ (*) 

An adaptable sequence can adapt to a sequence of any size. Two 
adaptable sequence types are always equivalent. 

Adaptable Heaps 

Use this format to specify an adaptable heap: 
HEAP (*) 

An adaptable heap can adapt to a heap of any size. Two adaptable 
heap types are always equivalent. 
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This chapter describes expressions and statements that can be used 
within a CYBIL program, procedure, or function. 

Expressions 5-1 

Operands 5-1 

Operators 5-1 

Negation Operator 5-2 

Multiplication Operators 5-2 

Sign Operators 5-4 

Addition Operators 5-5 

Relational Operators 5-7 

Set Operators 5-12 

Statements 5-15 

Assignment Statement 5-15 

Structured Statements 5-18 

BEGIN Statement 5-19 

FOR Statement 5-20 

REPEAT Statement 5-23 

WHILE Statement 5-24 

Control Statements 5-26 

IF Statement 5-27 

CASE Statement 5-29 

CYCLE Statement 5-31 

EXIT Statement 5-33 

RETURN Statement 5-34 

Storage Management Statements 5-35 

RESET Statement 5-39 

NEXT Statement 5-41 

ALLOCATE Statement 5-42 

FREE Statement 5-44 

PUSH Statement 5-45 
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Expressions 

Expressions are made up of operands and operators. Operators act on 
operands to produce new values. (Constant expressions are evaluated 
to provide values for constants. Refer also to Constant Expressions in 
chapter 2.) 

In general, operations involving nonequivalent types are not allowed; 
one type cannot be used where another type is expected. Exceptions 
are noted in the following descriptions. 

Operands 

Operands hold or represent the values to be used during evaluation of 
an expression. An operand can be a variable, constant, name of a 
constant, set value constructor, function reference (either standard 
function or user-defined function), pointer to a procedure name, pointer 
to a variable, or another expression enclosed in parentheses. 

The value of a variable being used as an operand is the last value 
assigned to it. A constant name is replaced by the constant value 
associated with it in the constant declaration. 

A function reference causes the function to be executed; the value 
returned by the function takes the place of the function reference in 
the expression. 

Operators 

Operators cause an action to be performed on one operand or a pair of 
operands. Many of the operators can be used only on basic types; they 
will be noted in their individual descriptions. Some operators can be 
used on sets. Although they are discussed in the individual 
descriptions that follow, for a more detailed description also refer to 
Set Operators later in this chapter. 

An operation on a variable or component of a variable that has an 
undefined value will produce an undefined result. 
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There are five kinds of operators, many of which are identified by 
reserved symbols. They are listed next in the order in which they are 
evaluated, from highest to lowest precedence, 

• Negation operator (NOT) 

• Multiplication operators ( * , DIV, / , MOD, and AND) 

• Sign operators ( + and -) 

• Addition operators ( + , - , OR, and XOR) 

• Relational operators (<,<=,>,>=, = ,<>, and IN) 

In relational operators that consist of two symbols (that is, < = , > = , 
and <>), do not separate the symbols with a space or any other 
character; the symbols must appear together. 

When an expression contains two or more operators of the same 
precedence, operations are performed from left to right. The only way 
to explicitly change the order of evaluation is to use parentheses. 
Parentheses specify that the expression inside them should be 
evaluated first. 

Negation Operator 

The negation operator, NOT, applies only to boolean operands. 
NOT TRUE equals FALSE. NOT FALSE equals TRUE. 

Multiplication Operators 

The multiplication operators perform multiplication and set 
intersection (*), integer quotient division (DIV), real quotient division 
(/). remainder division (MOD), and the logical AND nneratinn fANDV 
Table 5-1 shows the multiplication operators, the permissible types of 
their operands, and the type of result they produce. 
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Operator 


Operation 


Type of 
Operand 


Type of 
Result 


* 


Multiplication 


Integer or subrange of 


Integer 






Real 


Real 


* 


Set intersection 


Set of a scalar type 


Set of the 
same type 


DIV 


Integer quotient 1 


Integer or subrange of 
integer 


Integer 


/ 


Real quotient 


Real 


Real 


MOD 


Remainder 2 


Integer or subrange of 
integer 


Integer 


AND 


Logical AND 3 


Boolean 


Boolean 



1. Integer quotient refers to the whole number that results from a 
division operation; the remainder is ignored. A more formal definition 
is: for positive integers a, b, and n, a DIV b = n where n is the 
largest integer so that b * n < = a. 

For one or two negative integers, 

(-a) DIV b = (a) DIV (-b) = - (a DIV b) and 
(-a) DIV (-b) = a DIV b 

2. Remainder refers to the remainder of a division operation. A more 
formal definition is: 

a MOD b = a - (a DIV b) * b 

3. The logical AND operation is evaluated as follows: 

TRUE AND FALSE = FALSE 
TRUE AND TRUE = TRUE 
FALSE AND FALSE = FALSE 
FALSE AND TRUE = FALSE 

When the first operand is FALSE, the second operand is never 
evaluated. 
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Sign Operators 

The sign operators perform the identity operation (+) and sign 
inversion and set complement operation (-). Table 5-2 shows the sign 
operators, the permissible types of their operands, and the type of 
result they produce. 

Table 5-2. Sign Operators 



Operator Operation 



Type of 
Operand 



Type of 
Result 



Identity (indicates 
a positive 
operand) 



Sign inversion 
(indicates a 
negative operand) 



Set complement 



Integer 



Real 
Integer 

Real 

Set of a scalar type 



Integer 

Real 
Integer 

Real 

Set of the 
same type 
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The addition operators perform addition and set union (+), 
subtraction, boolean difference, and set difference (-), the logical OR 
operation (OR), and the exclusive OR operation (XOR). Table 5-3 
shows the addition operators, the permissible types of their operands, 
and the type of result they produce. 

Table 5-3. Addition Operators 



Operator 


Operation 


Type of 
Operand 


Type of 
Result 


+ 


Addition 


Integer or subrange of 
integer 


Integer 






Real 


Real 


+ 


Set union 


Set of a scalar type 


Set of the 
same type 


- 


Subtraction 


Integer or subrange of 
integer 


Integer 






Real 


Real 


- 


Boolean 
difference 1 


Boolean 


Boolean 


- 


Set difference 


Set of a scalar type 


Set of the 
same type 



1. The boolean difference operation is evaluated as follows: 

TRUE - TRUE = FALSE 
TRUE - FALSE = TRUE 
FALSE - TRUE = FALSE 
FALSE - FALSE = FALSE 



(Continued) 
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Table 5-3. 


Addition Operators (Continued) 






Operator 


Operation 


Type of 
Operand 




Type of 
Result 


OR 


Logical OR 2 


Boolean 




Boolean 


XOR 


Exclusive OR 3 


Boolean 




Boolean 


XOR 


Symmetric 
difference 


Set of a scalar 


type 


Set of the 
same type 



2. The logical OR operation is evaluated as follows: 

TRUE OR TRUE = TRUE 
TRUE OR FALSE = TRUE 
FALSE OR TRUE = TRUE 
FALSE OR FALSE = FALSE 

When the first operand is TRUE, the second operand is never 
evaluated. 

3. The exclusive OR operation is evaluated as follows: 

TRUE XOR TRUE = FALSE 
TRUE XOR FALSE = TRUE 
FALSE XOR TRUE = TRUE 
FALSE XOR FALSE = FALSE 



5-6 CYBIL Language Definition Revision F 

01/22/87 19:59:24 | 02/13/87 09:46:31 | 87/03/25 22.17.32 | 60464113 F | EXPRESSIONS AND STATEMENT | DRAFT COPY 



Operators 



T3_!_ii ? f\ i 

xvexauuiitu upeituuiB 



The relational operators (<, < = , >, > = , =, <>, and IN) test 
whether the following given conditions are true or false: less than 
(<), less than or equal to or subset of a set (<=), greater than (>), 
greater than or equal to or a superset of a set (> =), equal to or set 
identity (=), not equal to or set inequality (<>), and set membership 
(IN). 

Because relational operators are valid on so many different types, 
some special points about each type are noted next. Following these 
comments, table 5-4 lists the relational operators and the permissible 
types of their operands; they always produce a boolean type result. 

Comparison of Scalar Types 

The comparison operators (<,<=,>,>=, = , and < > ) are 
allowed only between operands of the same scalar type or between a 
substring of length i and a character. 

For integer type operands, the relationships all have their usual 
meaning. 

For character type operands, each character is essentially mapped to 
its corresponding integer value according to the ASCII collating 
sequence. (This is the same operation performed by the $INTEGER 
function described in chapter 6.) The operands and relational operators 
are then evaluated using the characters' integer values. 

For boolean type operands, FALSE is always considered to be less 
than TRUE. 

For ordinal type operands, operands are equal only if they are the 
same value; otherwise, they are not equal. For the other relational 
operators, each ordinal is essentially mapped to the corresponding 
integer value of its position in the ordinal list where it is defined. 
(This is the same operation performed by the $INTEGER function 
described in chapter 6.) The operands and relational operators are 
then evaluated using the ordinals' integer values. For an example, 
refer to the discussion of ordinal types under Scalar Types in chapter 
4. 

Operands that are a subrange of a scalar type can be compared with 
operands of the same type, including another subrange of the same 
type. 
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Comparison of Floating-Point Types 

All of the comparison operators are valid between operands of the real 
type. 

Comparison of Pointer Types 

Two pointers can be compared if they are pointers to equivalent or 
potentially equivalent types. (For further information on equivalent 
types, refer to Equivalent Types in chapter 4.) For potentially 
equivalent types, one or both of the pointers can be pointers to 
adaptable or bound variant types. The current type of such a pointer 
must be equivalent to the type of the pointer with which it is being 
compared; if it is not, the operation is undefined. 

Pointers can be compared for equality and inequality only. Two 
pointers are equal if they designate the same variable or if they both 
have the value NIL. A pointer of any type can be compared with the 
value NIL. Two pointers to a procedure are equal if they designate 
the same declaration of a procedure. 

Comparison of Relative Pointers 

Two relative pointers can be compared only if they are of equivalent 
types. Two relative pointers are equal if they can be converted to 
equal pointers using the #PTR function (described in chapter 6). 
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All of the comparison operators are valid between operands that are 
strings. If the lengths of the two string operands are unequal, spaces 
are added to the right of the shorter string to fill the field. 

Strings are compared character by character from left to right; that 
is, each character from one string is compared with the character in 
the corresponding position of the second string. Each character is 
compared using the same method as for operands of character type; 
the integer value of the character, when mapped to the ASCII 
collating sequence, is used. 

Comparison of Sets and Set Membership 

Comparison operators have slightly different meanings for sets than 
for other types. The only comparison operators valid for sets are: = 
(identical to), <> (different from), < = (the left operand is contained 
in the right operand), and > = (the left operand contains the right 
operand). These operators are valid between two sets of the same 
type. Their exact meanings are detailed later in this chapter under 
Set Operators. 

The other relational operator for sets is IN. A specified operand is IN 
a set if that operand is a member of the set. The set must be of the 
same type or a subrange of the same type as the operand. The 
operand can be a subrange of the type of the set. 

Comparison of Other Types 

Invariant records can be compared for equality and inequality only. 
Two equivalent records are equal if their corresponding fields are 
equal. 

The following types cannot be compared: 

• Arrays or structures that contain an array as a component or field 

• Variant records 

• Sequences 

• Heaps 

• Records that contain a field of one of the preceding types 
However, pointers to these types can be compared. 
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Table 5-4. Relational Operators 



Operator 


Operation 


Type of Left 
Operand 


Type of Right 
Operand 


< 


Less than 


Any scalar type 


The same scalar 
type 






Real 


Real 


< = 


Less than or 
equal to 


A string 


A string of the 
same length 


> 


Greater than 


A string of 
length l 1 


A character 


> = 


Greater than or 
equal to 






= 


Equal to 


A character 


A string of 
length l 1 


<> 


Not equal to 






IN 


Set membership 


Any scalar type 


A set of the 

same type 






Real 


A set of real 
type 






A string of 
length l 1 


A set of 
character type 



1. The string of length 1 has the form 

STRING(position) 
where the length is implied. The form 

STRING(position,l) 
is not valid in this case. 



(Continued) 
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Operator 


Operation 


Type of Left 
Operand 


Type of Right 
Operand 


= 


Equality (also 
called identity) 


A set of any 
scalar type 


A set of the 
same type 


<> 


Inequality 


A set of real 
type 


A set of real 
type 


< = 


Is contained in 






> = 


Contains 






<> 


Equality 
Inequality 


A nonvariant 
record type 
containing no 
arrays 


The same type 






Any pointer type 
or the value NIL 


The same type or 
the value NIL 
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Set Operators 

The set operators have already been mentioned briefly in the 
preceding sections on multiplication, sign, addition, and relational 
operators. This section discusses all of them and explains how they 
are used with sets. 

The set operators perform assignment, union (+), intersection (*), 
difference (-), symmetric difference (XOR), negation (-), identity or 
equality ( = ), inequality (<>), inclusion (<=), containment (>=), 
and membership (IN). 

Assignment is discussed under Sets in chapter 4. The next five 
operations (union, intersection, difference, symmetric difference, and 
negation) all produce results that are sets (they are described in table 
5-5). The remaining operations (identity, inequality, inclusion, 
containment, and membership) produce boolean results (they are 
described in table 5-6). 

The relational operations described in table 5-6 occur only after any 
operations described in table 5-5 have been performed. 
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Operator 



Operation 



Resulting Set 



Union All members of both sets. The result 

of A + B is all elements of sets A 
and B. 

Difference Members in the lefthand set that are 

not in the righthand set. The result 
of A - B is the elements of A that 
are not in B. This operation differs 
from negation in that two operands 
are present. 

Members that are in both sets. The 
result of A * B is all elements that 
are in both A and B. 

Members of the set's type that are 
not in the set. The result of -A is 
all elements of A's type that are not 
in A. This operation differs from the 
difference operation in that only one 
operand is present. 

Symmetric Members of either but not both sets. 

difference The result of A XOR B is all 

elements in A or B that are not 
common to both A and B. 



Intersection 



Negation 
(complement) 



XOR 
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Table 5-6. Operations That Produce Boolean Results 
Operator Operation Resulting Value 



Equality 
(identity) 



<> 



< = 



Inequality 



Inclusion 



TRUE if every member of one set is 
present in the other set and vice 
versa. A = B is TRUE if every 
element of A is in B and every 
element of B is in A. It is also 
TRUE if A and B are both empty 
sets. In any other case, it is FALSE. 

TRUE if not every member of one 
set is a member of the other set. 
A <> B is TRUE if A = B is 
FALSE. 

TRUE if every member of the 
lefthand set is also a member of the 
righthand set. A < = B is TRUE if 
every element of A is in B. It is also 
TRUE if A is an empty set. In all 
other cases, it is FALSE. 

TRUE if every member of the 
righthand set is also a member of 
the lefthand set. A > = B is TRUE 
if every element of B is in A (that 
is, B <= A). 

Membership TRUE if the scalar is of the same 

tvn*i a<z {.ho fvrui nf +V»o etif a-nA 4o 
-*/*-- — — ~ vr v WJ - «**~ *,«*-, ****** **, 

an element within the set. This 
operation differs somewhat from the 
others in that it can specify a value 
or a variable as an operand, rather 
than a set. It has the form 

scalar IN set 

where scalar can be a value 
(including a subrange) or a variable. 
A IN B is TRUE if A is the same 
type as the set B and A is an 
element of B. 



> = 



Containment 



IN 
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Statements 

Statements specify actions to be performed. Unlike declarations, 
statements can be executed. They can appear only in a program, 
procedure, or function. 

A statement list is an ordered sequence of statements. In a statement 
list, a statement is separated from the one following it by a 
semicolon. Two consecutive semicolons indicate an empty statement, 
which means no action. 

Statements can be divided into four types depending on their purpose 
or nature: 

• Assignment 

• Structured 

• Control 

• Storage management 

Assignment Statement 

The assignment statement assigns a value to a variable. 
Use this format for the assignment statement: 
name := expression; 

name 

Name of a variable previously declared. 

expression 

An expression that meets the requirements stated earlier in 
this chapter. Any constant or variable contained in the 
expression must be defined and have a value assigned. 

This statement is similar to the initialization part of the VAR 
declaration where you can assign an initial value to a variable. (For 
further information on initialization, refer to Variable Declaration in 
chapter 3.) The assignment statement allows you to change that value 
at any point in the program. The expression is evaluated and the 
result becomes the current value of the named variable. 
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The variable cannot be: 

• A read-only variable 

• A formal value parameter of the procedure that contains the 
assignment statement 

• A bound variant record 

• The tag field name of a bound variant record 

• A heap 

• An array or record that contains a heap 

The type of the expression must be equivalent to the type of the 
variable, with the exceptions discussed next. Both types can be 
subranges of equivalent types. 

A character, string, or substring variable can be assigned the value of 
a character expression, a string, or a substring. If you assign a value 
that is shorter than the variable or substring to which it is being 
assigned, spaces are added to the right of the shorter string to fill the 
field. If you assign a value that is longer than the variable or 
substring, the value is truncated on the right. Assigning strings or 
substrings that overlap is not a valid operation, for example, 
STRING_1 := STRING_1(3,7); results are unpredictable. 

If the variable is a pointer, its scope must be less than or equal to 
the scope of the data to which it is pointing. For example, a static 
pointer variable should not point to an automatic variable local to a 
procedure. When the procedure is left, the pointer variable will be 
pointing at undefined data. 
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a pointer to a Douna variant recora can De assigned a pointer to a 
variant record that is not bound and is otherwise equivalent. 

An adaptable pointer can be assigned either a pointer to a type to 
which it can adapt, or an adaptable pointer that has been adapted to 
one of those types. Both the type of the expression and its value are 
assigned, thus setting the current type of the adaptable pointer. 

Any fixed pointer except a pointer to sequence can be assigned a 
pointer to cell. After the assignment, the #LOC function (described in 
chapter 6) performed on the fixed pointer would return the same 
value as the pointer to cell. 

A pointer to cell can be assigned any pointer type. The value assigned 
is a pointer to the first cell allocated for the variable to which the 
pointer being assigned points. 

When assigning pointers, remember that the object of a pointer has a 
different lifetime than the pointer variable. Automatic variables are 
released when the block in which they are declared has been 
executed. Allocated variables no longer exist when they are explicitly 

reitsitseu wiul uie rxvEiiii swtwjiiieiit. i-in ai>i«iuj>k U) reieience a. voiiauie 

beyond its lifetime causes an error and unpredictable results to occur. 

A variant record can be assigned a bound variant record of types that 
are otherwise equivalent. 

The colon (:) and equals sign ( = ) symbols together are called the 
assignment operator. When used as the assignment operator, there can 
be no spaces or comments between the two symbols. 
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Structured Statements 

A structured statement contains one or more statements that are 
called, collectively, a statement list. The structured statement 
determines when the statement list it contains will be executed. 

There are four structured statements: 

Statement Description 

BEGIN Provides a logical grouping of statements that 

performs a specific function. 

FOR Executes a list of statements while a variable is 

incremented or decremented from an initial value to a 
final value. 

REPEAT Executes a list of statements until a specified 

condition is true. The test is made after each 
execution of the statements. 

WHILE Executes a list of statements while a specified 

condition is true. The test is made before each 
execution of the statements. 

The IF and CASE control statements (described later in this chapter) 
also contain statement lists. The structured statements, the IF 
statement, and the CASE statement can be nested within each other 
up to 63 levels. The FOR statement can be nested 15 levels. 
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The BEGIN statement executes a single statement list once; there is 
no repetition. This statement logically groups statements that perform 
a particular function and improves readability. 

Use this format for the BEGIN statement: 

{/label/} 
BEGIN 

statement list; 

END {/label/} ; 

label 

Name that identifies the BEGIN statement and the statement 
list contained in it. Use of labels is optional. If you use a label 
before BEGIN, it is recommended that you use one after END, 
but it is not required. If you use labels in both places, they 
must match. The label name must be unique within the block 
in which you use it. 

statement list 

One or more statements. 

Declarations are not allowed with the BEGIN statement. Execution of 
the BEGIN statement ends when either the last statement in the list 
is executed or control is explicitly transferred from within the list. 
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FOR Statement 

The FOR statement executes a statement list repeatedly while a 
special variable ranges from an initial value to a final value. There 
are two formats for the FOR statement: one that increments the 
variable and one that decrements the variable. 

Use this format to increment the variable: 

{/label/} 

FOR name := initial. value TO final_ value DO 

statement list; 
FOREND {/label/} ; 

Use this format to decrement the variable: 

{/label/} 

FOR name := initial_value DOWNTO final_value DO 
statement list; 

FOREND {/label/} ; 

label 

Name that identifies the FOR statement and the statement list 
contained in it. Use of labels is optional. If you use a label 
before FOR, it is recommended that you use one after 
FOREND, but it is not required. If you use labels in both 
places, they must match. The label name must be unique 
within the block in which you use it. 

name 

Name of the variable that controls the number nf repetitions of 
the statement list. This variable keeps track of the number of 
iterations performed or the current position within the range of 
values. 

initial _ value 

Scalar expression specifying the initial value assigned to the 
variable. 
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Scalar expression specifying the final value to be assigned to 
the variable if the statement ends normally. If the statement 
ends abnormally or as the result of an EXIT statement, this 
may not be the actual final value. 

statement list 

One or more statements. 

The variable, initial value, and final value must be of equivalent 
scalar types or subranges of equivalent types. The variable cannot be 
assigned a value within the statement list, or be passed as a reference 
parameter to a procedure called within the statement list. Either 
condition causes a fatal compilation error. The variable cannot be an 

When CYBIL encounters a FOR statement that increments (one 
containing the TO clause), it evaluates the initial value and final 
value. If the initial value is greater than the final value, the FOR 
statement ends and execution continues with the statement following 
FOREND; the statement list is not executed. If the initial value is 
less than or equal to the final value, the initial value is assigned to 
the control variable and the statement list is executed. Then, the 
control variable is incremented by one value and, for each increment, 
the statement list is executed. This sequence of actions continues 
through the final value. For example, the statement 

FOR i = 1 TO 5 DO 
FOREND ; 

causes the statement list to be executed five times, that is, while I 
takes on values from 1 to 5. Then the FOR statement ends. Execution 
continues at the statement following FOREND with the variable I 
having a value of 5. 
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When CYBIL encounters a FOR statement that decrements (one 
containing the DOWNTO clause), it performs a similar process. If the 
initial value is less than the final value, the FOR statement ends and 
execution continues with the statement following FOREND. If the 
initial value is greater than or equal to the final value, the initial 
value is assigned to the control variable and the statement list is 
executed. The control variable is decremented by one value and, for 
each decrement, the statement list is executed. When the control 
variable reaches the final value and the statement list is executed the 
last time, the FOR statement ends. 

The initial value and final value expressions are evaluated once, when 
the statement is entered; the values are then held in temporary 
locations. Thus, subsequent assignments to initial value and final 
value have no effect on the execution of the FOR statement. 

When a FOR statement completes normally, the value of the control 
variable is that of the final value specified in the statement. This may 
not be the case if the statement ends abnormally or ends as a result 
of an EXIT statement. 

FOR statements can be nested in up to 15 levels. 

Example: 

Integer values are often used in FOR statements, but any scalar type 
can be used. The following example executes a statement list while 
the value of a character variable is incremented. 

FOR control := 'a' TO 'z' DO 
FOREND; 

Each time the statement list is performed, the value of CONTROL 
increases by one value, following the normal sequence of alphabetic 
characters from 'a' to Y; that is, after the statement list is executed 
once, the value of CONTROL changes to 'b', and so on until the 
statement list has been executed 26 times. 
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The REPEAT statement executes a statement list repeatedly until a 
specific condition is true. 

Use this format for the REPEAT statement: 

{/label/} 
REPEAT 

statement list; 
UNTIL expression; 

label 

Name that identifies the REPEAT statement and the statement 
list contained in it. Use of the label before REPEAT is 
optional; a label is not permitted after UNTIL. The label name 
must be unique within the block in which it is used. 

S TrSk X© 1 1 1 © O X USX 

One or more statements. 

expression 

A boolean type expression. 

The statement list is always executed at least once. After the last 
statement in the list, the expression is evaluated. Every time the 
expression is FALSE, the statement list is executed again. When the 
expression is TRUE, the REPEAT statement ends and execution 
continues with the statement following the UNTIL clause. 

The statement list can contain nested REPEAT statements. 

Example: 

In this example, the statement list (mod operation and assignments) is 
executed once. If J is not equal to zero, it is executed again and 
continues until J is equal to zero. 



REPEAT 



= i MOD j; 
= j; 
= k; 



UNTIL j 
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WHILE Statement 

The WHILE statement executes a statement list repeatedly while a 
specific condition is true. 

Use this format for the WHILE statement: 

{/label/} 

WHILE expression DO 

statement list; 
WHILEND {/label/} ; 

label 

Name that identifies the WHILE statement and the statement 
list contained in it. Use of labels is optional. If you use a label 
before WHILE, it is recommended that you use one after 
WHILEND, but it is not required. If you use labels in both 
places, they must match. The label name must be unique 
within the block in which you use it. 

expression 

A boolean type expression. 

statement list 

One or more statements. 

If the boolean expression is evaluated as TRUE, the statement list is 
executed. After the last statement in the list, the expression is again 
evaluated. Every time the expression is TRUE, the statement list is 
executed. When the expression is FALSE, the WHILE statement ends 
aiiu CAU.UUUU wuumucb wiLii une suneiiieiiL luiiuwuig vvniLiHirNU. ll 

the expression is FALSE in the initial evaluation, the statement list is 
never executed. 
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Kxample: 

In this example, the expression TABLE[I] <> is evaluated; an 
element of the array TABLE is compared to 0. While the expression 
is true (the element is not 0), I is incremented. This causes the next 
element of the array to be checked. When the expression is false, the 
statement list is not executed. Execution continues with the statement 
following WHILEND. I is the position of an element in the array that 
is 0. 

/check_for_zero/ 
WHILE table [i] <> DO 

i := 1 + 1; 
WHILEND /check.f or.zero/ ; 

The preceding example assumes, of course, that the array contains an 
element with the value 0. If not, the WHILE statement list executes 
in an infinite loop. In either the WHILE expression or the statement 
list, there must be a check. One solution is to set a variable, 
TABLE _ MAX, to the maximum number of elements in the array and 
check it before executing the statement list, as in: 

WHILE (i < table_max) AND (table [i] <> 0) DO 

Now both expressions must be true before the statement list is 

false, execution continues following WHILEND. 
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Control Statements 

A control statement can change the flow of execution of a program by 
transferring control from one place in the program to another. 

There are five control statements: 

Statement Description 

IF Executes one statement list if a given condition is 

true; ends the statement or executes another statement 
list if the condition is false. 

CASE Executes one statement list out of a set of statement 

lists, depending on the value of a given expression. 

CYCLE Causes the remaining statements in a repetitive 

statement (FOR, REPEAT, or WHILE) to be skipped 
and the next iteration of the statement to occur. 

EXIT Unconditionally stops execution within a procedure, 

function, or a structured statement (BEGIN, REPEAT, 
WHILE, and FOR). 

RETURN Returns control from a procedure or function to the 

point at which it was called. 

The structured statements (described earlier in this chapter) contain 
statement lists like the IF and CASE statements. The structured 
statements, the IF statement, and the CASE statement can be nested 
within each other up to 63 levels. 

Procedure and function calls also transfer control of an executing 
program. Functions are discussed in chapter 6 and procedures are 
discussed in chapter 7. 
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The IF statement executes or skips a statement list, depending on 
whether a given condition is true or false. 

Use this format for the IF statement: 

IF expression THEN 
statement list; 

{ELSEIF expression THEN 

statement list;}... 
{ELSE 

statement list;} 
IFEND; 

expression 

A boolean expression. 

statement list- 
One or more statements. 

The ELSEIF and ELSE clauses are optional. The ELSEIF clause 
contains another test condition that is evaluated only if the preceding 
condition (expression) is false. The ELSE clause provides a statement 
list that is executed unconditionally when the preceding expression is 

false. 

When an expression is evaluated as true, the statement list following 
the reserved word THEN is executed. When the list is completed, 
execution continues with the first statement following IFEND. If the 
expression is false, execution continues with the next clause or 
reserved word in the IF statement format (that is, ELSEIF, ELSE, or 
IFEND). 
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If the next reserved word in the IF statement format is IFEND, 
execution continues with the first statement following it. 

If the next reserved word is ELSEIF, the expression contained in that 
clause is evaluated; if true, the statement list that follows is executed. 
Otherwise, execution continues with the next reserved word in the IF 
statement format. 

If the next reserved word is ELSE, the statement list that follows is 
always executed. You get to this point only if the preceding 
expression(s) is false. 

Additional IF statements can be contained (nested) in any of the 
statement lists. A consistent style of indentation or spacing, such as 
that provided by the CYBIL source code formatter, greatly improves 
the readability of such statements. (The source code formatter is 
described in chapter 8.) 

If the ELSE clause is included in a nested IF statement, the clause 
applies to the most recent IF statement. 

Examples: 

In this example, Y is assigned to X only if X is less than Y. 

IF x < y THEN 

X := y; 
IFEND; 

In the next example, Z is always assigned one of the values 1, 2, 3, 
or 4 depending on the value of X. 

IF x <= 5 THEN 

Z := 1; 
ELSEIF X > 30 THEN 

Z := 2; 
ELSEIF x = 15 THEN 

Z := 3; 
ELSE 

Z := 4; 
IFEND; 
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The CASE statement executes one statement list out of a set of lists, 
based on the value of a given expression. 

Use this format for the CASE statement: 

CASE expression OF 
= value {,value}... = 
statement list; 

{= value {,value}... = 

statement list;}... 
{ELSE statement list;} 
CASEND; 

expression 

A scalar expression. The expression must be of the same type 
as the value or values that follow. 

value 

One or more constant scalar expressions or a subrange of 
constant scalar expressions. A subrange indicates that all of the 
values included in the subrange are acceptable values. If you 
specify two or more values, separate them with commas. The 
values must be of the same type as the expression. Values can 
be in any order, not strictly sequential. Values must be unique 
within the CASE statement. 

statement list 

One or more statements. 

You define a set of possible values that a variable or expression can 
have. With one or more of the values you associate a statement list 
using the format: 

= value = 

statement list; 

When the CASE statement is executed, the expression is evaluated 
and the statement list associated with the current value of the 
expression is executed. If the current value is not found among those 
in the CASE statement, execution continues with the ELSE clause. If 
ELSE is omitted and the value is not found in the CASE statement, 
the program is in error. After any one of the statement lists is 
executed, execution continues with the statement following CASEND. 
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Examples: 

In this example, I is a variable that is expected to take on one of the 
values -5 through 20. If its value is -5, -4, -3, -2, -1, or 0, the first 
statement list (X := X) is executed and control goes to the statement 
following CASEND. If the value of I is 1, the second statement list is 
executed, and so on. 

CASE i OF 

= -5, -4, -3, -2, -1, = 

X := X; 
= 1 = 

X := X + 1; 
= 2 = 

X := X + 2; 
= 3 = 

X := X + 3; 
= 4 = 

X := X + 4; 
=5 . . 20 = 

X := X + 5; 
CASEND; 

In the next example, OPERATOR is a variable that is expected to 
take on values of PLUS, MINUS, or TIMES. Depending on the current 
value of OPERATOR, the associated statement is executed. 



CASE operator 


OF 


= plus = 






X := X + 


y; 




= minus = 






X := X - 


y; 




= times = 






X := X * 


y; 




r-i fr- 

LLOL 






X := 0; 






V := 0; 






CASEND; 
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v/iv/juiii otausmtJiii 

The CYCLE statement can be included in the statement list of a 
repetitive statement (FOR, REPEAT, or WHILE) and causes any 
statements following it to be skipped and the next iteration of the 
repetitive statement to occur. 

Use this format for the CYCLE statement: 

CYCLE /label/; 

label 

Name that identifies the repetitive statement in which the 
CYCLE statement is contained. 

The CYCLE statement is usually used in conjunction with an IF 
statement, as in: 

/labeV 

repetitive statement 
IF expression THEN 

IFEND; 

remainder of statement list; 
end of repetitive statement; 

The IF statement tests for a condition that, if true, causes the CYCLE 
statement to be executed. Then the remaining statements of the 
repetitive statement are skipped and execution continues with 
whatever would normally follow the statement list, either another 
cycle of the repetitive statement or the next statement following the 
end of the repetitive statement. If the condition in the IF statement is 
false, the remaining statements in the repetitive statement are 
executed. 

If it is not contained in a repetitive statement, the CYCLE statement 
is diagnosed as a compilation error. 
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Example: 

This example finds the smallest element of an array TABLE. On the 
first execution, X (the first element of the array) is assumed to be 
smallest. If X is smaller than succeeding elements of the array, the 
CYCLE statement is executed; the remainder of the statements are 
then skipped, and the next iteration of the FOR statement occurs. If 
an element smaller than X is found, the CYCLE statement is ignored 
and the rest of the statement list is processed; X is replaced by the 
smaller element. If N has not yet been reached, the FOR statement 
continues. When N is reached, X will contain the smallest element of 
the array. 

x := table [1]; 

/f ind_ small est/ 

FOR k := 2 TO n DO 
IF x < table [k] THEN 

CYCLE /find. smallest/; 
I FEND; 

x := table [k]; 
FOREND /find_smallest/; 
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citabciucut 



The EXIT statement causes an unconditional exit from a procedure, 
function, or a structured statement (BEGIN, FOR, REPEAT, and 
WHILE). 

Use this format for the EXIT statement: 

EXIT name; 

name 

Name that identifies the procedure, function, or statement. For 
a procedure or function, it is the procedure or function name. 
For a structured statement, it is the statement label; in this 
case the format is: 

EXIT /label/; 

When the EXIT statement is encountered, execution of the named 
procedure, function, or statement is automatically stopped and 
execution resumes with the statement that would follow normal 

normally follow the procedure or function call. For a structured 
statement, it is the statement following the end of the structured 
statement (END, FOREND, UNTIL expression, and WHILEND). 

The EXIT statement must be within the scope of the procedure, 
function, or statement it names. Otherwise, it has no meaning and is 
diagnosed as a compilation error. 

With a single EXIT statement, you can exit several levels of 
procedures, functions, or statements; they need not be exited 
separately. (This is sometimes referred to as a nonlocal exit.) If the 
EXIT statement is executed in a nested recursive procedure or 
function, it is the most recent invocation of the procedure or function 
and any intervening procedures or functions that are exited. 
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Example: 

The following example declares an array of user names, then sets the 
variable KEY to one of the names. The statement list in the FOR 
statement labeled FIND_KEY searches the array for the key name. 
When it is found, the EXIT statement is executed and the FOR 
statement ends. Execution continues at the statement following the 
end of the FOR statement which is the end of the procedure. 

PROCEDURE ex1t_example; 

VAR 

i: integer, 
key: string(7), 

names: [READ] array [ 1 . . 4 ] of string(7) :=[' jqp8402' , 
'jxdl432', 'efd3204', 'led4411'] ; 

key := 'efd3204' ; 

/find. key/ 

FOR 1 := LOWERBOUND (names) TO UPPERBOUND (names) DO 
IF key = namesti] THEN 

EXIT /find_key/ ; 
IFEND; 
FOREND/find_key/; 
PROCEND exit_example; 

RETURN Statement 

The RETURN statement completes the execution of a procedure or 
lUnCbion auu returns control to me program, procedure, or i unction 
that called it. 

Use this format for the RETURN statement: 

RETURN; 

If it is omitted at the end of a procedure or function, the RETURN 
statement is assumed. 
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Storage Management Statements 

Storage Management Statements 

Storage management statements allow you to manipulate components 
of sequence and heap types, and put variables in the run-time stack. 

There are five storage management statements: 

Statement Description 

RESET Resets the pointer in a sequence or releases all the 

variables in a user-defined heap. 

NEXT Creates or accesses the next element of a sequence 

given a starting element. 

ALLOCATE Allocates storage for a variable in a heap. 

FREE Releases a variable from a heap. 

PUSH Allocates storage for a % T ariable in the run-time 

stack. 

C . 1.L _ T>T7C1x*m ] \TT7Vm _1._J.__ J._ TT _1_ _ 

sequences use wit: _v_-&_-± imu i>Hr_!_± s.£i.enieiiis. -leaps use uie 

RESET, ALLOCATE, and FREE statements. The run-time stack uses 
the PUSH statement. (Refer to Storage Types in chapter 4 for further 
information on sequences and heaps.) The NEXT and ALLOCATE 
statements can a±so be used to allocate space m a segment access i__e. 
Accessing a file as a memory segment is described in the CYBIL 
Sequential and Byte-Addressable Files manual. That manual also 
compares use of the default heap and run-time stack with use of a 
segment access file for data storage. 
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In the NEXT, ALLOCATE, and PUSH statements, you must specify a 
pointer to the variable to be manipulated so that sufficient space can 
be allocated for that type. This pointer can be a pointer to a fixed 
type, a pointer to an adaptable type, or a pointer to a bound variant 
record type. Space is then allocated for a variable of the type to 
which the pointer can point. This pointer is also used to access the 
variable. When space is allocated, CYBIL returns the address of the 
variable to the pointer. Therefore, to reference a variable in a 
sequence, heap, or the run-time stack, you indicate the object of the 
pointer in this form: pointer name *. 

If you specify a fixed type pointer, the statement uses a variable of 
the type designated by that pointer variable. If you specify an 
adaptable type pointer or bound variant record type pointer, you must 
also indicate the size of the adaptable type or the tag field of the 
variant record to be used. This causes a fixed type to be set and the 
adaptable or bound variant record pointer designates a variable of 
that fixed type. That particular fixed type is designated until it is 
reset by a subsequent assignment or another storage management 
statement. 
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±u inuicai« wie Size Oi an aua.pua.uie pointer or nie Lag Heiu ih a 
bound variant record pointer, you use the format: 

pointer : [size fixer] 

pointer 

Name of an adaptable pointer variable or a bound variant 
record pointer variable. 

size fixer 

Fixed amount of space required for the variable designated by 
pointer. You set the size of the adaptable type the same way 
you specify the size of the corresponding unadaptable (fixed) 
type. For example, in a variable or type declaration, you 
engcifv the size of a fixed arra v with subscript bounds usuall v 
a subrange of "scalar expression..scalar expression". You set 
the size of an adaptable array here using the same form. 
Summarized next are the forms used to set the size of all 
possible adaptable types. For more detailed information, refer 
to the descriptions of the corresponding fixed types in chapter 
4 



Pointer Type Form Used to Set Size 

Adaptable array 

Adaptable string 



Adaptable heap 

Adaptable 
sequence 

Adaptable record 



Bound variant 
record 



scalar expression .. scalar expression 

A positive integer expression specifying the 
length of the string 

[{REP positive integer expression OF} fixed 
type name {,{REP positive integer expression 
OF} fixed type name}..] 

[{REP positive integer expression OF} fixed 
type name {,{REP positive integer expression 
OF} fixed type name}..] 

One of the forms used for an adaptable 
array, string, heap, or sequence 

A scalar expression or one or more constant 
scalar expressions followed by an optional 
scalar expression 



Revision F 
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If an adaptable array had a lower bound specified in its original 
declaration, the lower bound specified here must match that value. 
For an adaptable record, the form used must be a value and type to 
which the record can adapt. For a bound variant record, the order, 
types, and values used must be valid for a variant of the record; all 
but the last of the expressions must be constant. 

Examples: 

This example declares a type that is an adaptable array named 
ADAPT_ARRAY. PTR is a pointer to that type. BUNCH is a heap 
with space for 100 integers. The heap BUNCH is reset; that is, any 
existing elements are released. Space is then allocated in the heap for 
a variable of the type designated by PTR. That variable is of type 
AD APT_ ARRAY (an array of integers) and it has fixed subscript 
bounds of from 1 to 15. PTR now points to that array. 

TYPE 

adapt_array = array [1 .. * ] of integer; 

VAR 

ptr: * adapt _ar ray, 

bunch: HEAP (REP 100 of integer); 

RESET bunch; 

ALLOCATE ptr: [1 .. 15] IN bunch; 

The following example shows the setting of an adaptable sequence. 
Notice that two sets of brackets are required in the PUSH statement. 

VAR 

ptr: *SEQ ( * ); 

PUSH ptr: [[REP 10 OF integer, REP 22 OF char]]; 
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The RESET statement operates on both sequences and heaps. In a 
sequence, it resets the pointer to the beginning of the sequence or to 
a specific variable within the sequence. In a heap, it releases all the 
variables in the heap. 

The RESET statement must appear before the first NEXT statement 
(for a sequence) or ALLOCATE statement (for a user-defined heap). 
This ensures that the sequence is at the beginning or the heap is 
empty. If you reserve space by using a NEXT or ALLOCATE 
statement before the RESET statement, the program is in error. 

RESET in a Sequence 

This statement sets the current element being pointed to in a 
sequence. 

Use this format for the RESET statement in a sequence: 

RESET sequence _ pointer / TO variable _pointer } ; 

sequence _pointer 

Name of a pointer to a sequence. This specifies the particular 
sequence. 

variable _pointer 

Name of a pointer to a particular variable within the sequence. 
If it is omitted, the pointer points to the first element of the 
sequence. 
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If you did not set the value of the variable_pointer with a NEXT 
statement for the same sequence, an error will occur. An error will 
also occur if the value of the variable _pointer is NIL. 

The RESET statement must appear before the first occurrence of a 
NEXT statement to reset the sequence to its beginning; otherwise, the 
program is in error. 

RESET in a Heap 

This statement releases the variables currently in a heap. 
Use this format for the RESET statement in a heap: 
RESET heap; 

heap 

Name of a heap type variable. 

Space for the variables is released and their values become undefined. 

Make sure that the RESET statement appears before the first 
occurrence of an ALLOCATE statement for a user-defined heap so that 
the heap is empty; otherwise, the program is in error. 
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The NEXT statement sets the specified pointer to designate the 
current element of the sequence and then makes the next element in 
the sequence the current element. This moves the pointer along the 
sequence, allowing you to assign values to and access elements. 

Use this format for the NEXT statement: 

NEXT pointer { : [size fixer] } IN sequence _ pointer; 

pointer 

Name of a pointer to a fixed type, an adaptable type, or a 
bound variant record type. The type pointed to by the pointer 
is the type of the variable in the sequence. These pointers are 
described in detail under Storage Management Statements 
earlier in this section. 

size fixer 

Size of an adaptable type or tag field of a bound variant record 
type. If it is omitted, the pointer must be a pointer to a fixed 
type. The forms used to specify size are described in detail 
under Storage Management Statements earlier in this section. 

sequence _ pointer 

Name of a pointer to a sequence. This specifies the particular 
sequence. 

After a RESET statement, the current element is always the first 
ciement* Oi. tne sequence, n. i^ijX.1 statement assigns u> ui6 speciiieu 
pointer the address of the current (first) element, and then makes the 
next element (the second) the new current element. Thus, the order of 
variables in a sequence is determined by the order in which the 
NEXT statements are executed. 

If the NEXT statement causes the new element to be outside the 
bounds of the sequence, the pointer is set to NIL. Before attempting 
to reference an element in a sequence, check for a NIL pointer value. 
If you use a pointer variable with a value of NIL to access an 
element, a run-time error will occur. 

The type of pointer you specify when data is retrieved from the 
sequence must be equivalent to the type you used when the same data 
was stored in the sequence; otherwise, the program is in error. 
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ALLOCATE Statement 

The ALLOCATE statement allocates storage space for a variable of 
the specified type in the specified heap and then sets the pointer to 
point to that variable. 

Use this format for the ALLOCATE statement: 

ALLOCATE pointer { .- [size fixer] } { IN heap } ; 

pointer 

Name of a pointer to a fixed type, adaptable type, or bound 
variant record type. These pointers are described in detail 
under Storage Management Statements earlier in this section. 

size fixer 

Size of an adaptable type or tag field of a bound variant record 
type. If it is omitted, the pointer must be a pointer to a fixed 
type. The forms used to specify size are described in detail 
under Storage Management Statements earlier in this section. 

heap 

Name of a heap type variable. If it is omitted, the default heap 
is assumed. 
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If there is not enough space for the variable to be allocated, the 
pointer is set to NIL. Before attempting to reference a variable in a 
heap, check for a NIL pointer value. If you use a pointer variable 
with a value of NIL to access data, a run-time error will occur. 

For a user-defined heap, you must include a RESET statement before 
the first occurrence of an ALLOCATE statement to ensure that the 
heap is empty; otherwise, the program is in error. (When you use the 
default heap, however, the RESET statement is done automatically 
and you should not specify it.) 

The lifetime of a variable that is allocated using the storage 
management statements is the time between the allocation of storage 
(with the ALLOCATE statement) and the release of storage (with the 
FREE statement). A variable allocated using an automatic pointer 
must be explicitly freed (using the FREE statement) before the block 
is left, or the space will not be released by the program. When the 
block is left, the pointer no longer exists and, therefore, the variable 
cannot be referenced. i± trie biOCK is en^ereu again, tue previous 
pointer and the variable referenced by the pointer cannot be 
reclaimed. Therefore, it is recommended that you free such variables 
before leaving the block. 
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FREE Statement 

The FREE statement releases the specified variable from the specified 
heap. 

Use this format for the FREE statement: 

FREE pointer { IN heap } ; 

pointer 

Name of the pointer variable that designates the variable to be 
released. 

heap 

Name of a heap type variable. If it .is omitted, the default heap 
is assumed. 

The variable's space in the heap is released and its value becomes 
undefined. The pointer variable designating the released variable is 
set to NIL. If you specify a variable that is not currently allocated in 
the heap, the results are unpredictable. 

Using a pointer variable with the value NIL to access data causes a 
run-time error to occur. Releasing the NIL pointer is also an error. 
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The PUSH statement allocates storage space on the run-time stack for 
a variable of the specified type and then sets the pointer to point to 
that variable. 

Use this format for the PUSH statement: 

PUSH pointer { : [size fixer] } ; 

pointer 

Name of a pointer to a fixed type, adaptable type, or bound 
variant record type. These pointers are described in detail 
under Storage Management Statements earlier in this section. 

size fixer 

Size of an adaptable type or tag field of a bound variant record 
type. If it is omitted, the pointer must be a pointer to a fixed 
type. The forms used to specify size are described in detail 
under Storage Management Statements earlier in this section. 

If there is not enough space for the variable to be allocated, the 
pointer is set to NIL. The value of the variable that has just been 
allocated is undefined until a subsequent assignment to the variable is 
made. 

You cannot release space on the run-time stack explicitly. It is 
released automatically when the procedure containing the PUSH 
statement completes. At that time, space for the variable is released 
and its value becomes undefined. 

Example: 

This example shows the declaration of a pointer variable named 
ARRAY_PTR that points to an adaptable array. The PUSH statement 
allocates space in the run-time stack for a fixed array of from 1 to 20 
elements. Elements of the array can be referenced by ARRAY_ 
PTR'ti], where i is an integer from 1 to 20. 

VAR 

array_ptr: "array [1 .. * ] of integer; 
PUSH array_ptr: [1 .. 20]; 
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This chapter describes the functions that are predefined in CYBIL and 
explains how to define your own functions. 

Standard Functions 6-2 

$CHAE Function 6-2 

$INTEGER Function 6-3 

#LOC Function 6-4 

LOWERBOUND Function 6-4 

LOWERVALUE Function 6-5 

PRED Function 6-6 

#PTR Function 6-7 

$REAL Function 6-8 

#REL Function 6-8 

#SEQ Function 6-9 

#SIZE Function 6-10 

STRLENGTH Function 6-11 

SUCC Function 6-12 

UPPERBOUND Function 6-13 
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Functions 



A function is one or more statements that perform a specific action 
and can be called by name from a statement elsewhere in a program. 
A reference to a function causes actual parameters in the calling 
statement to be substituted for the formal parameters in the function 
declaration and then the function's statements to be executed. Usually 
the function computes a value and returns it to the portion of the 
program that called it. 

A function differs from a procedure in that the value returned for a 
function replaces the actual function reference within the statement. A 
function is a valid operand in an expression; the value returned by 
the function replaces the reference and becomes the operand. 

The value of a function is the last value assigned to it before the 
function returns to the point where it was called. The reason for its 
return doesn't matter; it could complete normally or abnormally. If the 
function returns for any reason before a value is assigned to the 
function name, results are undefined. 

Functions can be recursive; that is, a function can call itself. In that 
case, however, there must be some provision for ending the calls and 
the code within the function must not modify itself. Appendix F, The 
OYljlLi Ivun-xime rjnvironment, describes now recursive lunciiions are 
managed. 

You can call standard functions that are already defined in the 
CYBIL language, you can define your own functions, or you can call 
functions designed specifically for use on NOS/VE. This chapter 
describes all three. 

Functions that start with $ are data conversion functions. Functions 
that start with # are either system-dependent functions (that is, 
unique to CYBIL on NOS/VE) or functions whose results are system 
dependent. (For example, #SIZE is a standard function available on 
all variations of CYBIL regardless of operating system; however, its 
results vary depending on the system on which it is being used.) 
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Standard Functions 

The functions described here are standard CYBIL functions. They can 
be used safely in variations of CYBIL available on other operating 
systems. Under System-Dependent Functions, later in this chapter, 
you'll find descriptions of functions unique to CYBIL on NOS/VE. 

The functions are described in alphabetical order. 

$CHAR Function 

The $CHAR function returns the character whose ordinal number 
within the ASCII collating sequence is that of a given expression. 

Use this format for the $CHAR function call: 

$CHAR(expression) 

expression 

An integer expression whose value can be from to 255. 

If you specify a value for the integer expression less than or greater 
than 255, an error occurs. 
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$1NTEGER Function 

The $INTEGER function returns the integer value of a given 
expression. 

Use this format for the $INTEGER function call: 

$INTEGER(expression) 

expression 

An expression of type integer, subrange of integer, boolean, 
character, ordinal, or real. 

Expression Value Returned 



integer 
Boolean 

Character 

Ordinal 

Real 



The value of that expression is returned. 

Zero is returned for a false expression and 1 is 
returned for a true expression. 

The ordinal number of the character in the ASCII 
collating sequence is returned. 

The ordinal number associated with that ordinal value 
is returned. The value returned for the first element 
of an ordinal type is 0, the second element is 1, and 
so on. 

The value of the expression is truncated to a whole 
number. If the number is in the range defined for 
integers, that number is returned; otherwise, an 
out-of-range error occurs. 
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#LOC Function 

The #LOC function returns a pointer to the first cell allocated for a 
given variable. 

Use this format for the #LOC function call: 

#LOC(name) 

name 

Name of a variable. 

If the specified variable is a formal value parameter, the pointer 
cannot be used to modify the variable. 

LOWERBOUND Function 

The LOWERBOUND function returns the lower bound of an array's 
subscript bounds. 

Use this format for the LOWERBOUND function call: 

LOWERBOUND(array) 

array 

An array variable or the name of a fixed array type. 

The type of the value returned is the same as the type of the array's 
subscript bounds. 

Example: 

Assuming the following declaration has been made 

v.AR 

x: array [1 .. 100] of boolean, 
y: array ['a' .. 't'] of integer; 

the value of LOWERBOUND(X) is 1; the value of LOWERBOUND(Y) 
is 'a'. 
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LOWERVALUE Function 

The LOWERVALUE function returns the smallest possible value that 
a given variable or type can have. 

Use this format for the LOWERVALUE function call: 

LOWERVALUE(name) 

name 

A scalar variable or name of a scalar type. 

The type of the value returned is the same as the given type. 

Examples: 

Assuming the following declaration has been made 

VAR 

dozen: 1 .. 12; 

the value of LOWERVALUE(DOZEN) is 1. 

After the declarations 

TYPE 

t = (first, second, third); 

VAR 

V: t; 

the value of LOWERVALUE(V) is FIRST and the value of 
LOWERVALUE(T) is FIRST. 
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PRED 

PRED Function 

The PRED function returns the predecessor of a given expression. 
Use this format for the PRED function call: 
PRED(expression) 

expression 

A scalar expression. 

If the predecessor of the expression does not exist, the program is in 
error. 

Example: 

The following example declares two variables, WARM and COLD, each 
of which can take on ordinal values of the type SEASONS. The 
variable WARM is assigned the value SPRING while the variable 
COLD is assigned the value WINTER. 

TYPE 

seasons = (winter, spring, summer, fall); 

VAR 

warm: seasons, 
cold: seasons; 

warm := spring; 
cold := PRED (warm); 
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fn'K function 

The #PTR function returns a pointer that can be used to access the 
object of a relative pointer. 

Use this format for the #PTR function call: 

#PTR(pointer_name {,parent_name} ) 

pointer _ name 

Name of the relative pointer variable. 

parent _name 

Name of the variable that contains the components being 
designated by relative pointers. If omitted, the default heap is 
used. The variable can be a string, array, record, heap, or 
sequence type (either fixed or adaptable). 

Relative pointers cannot be used to access data directly. The #PTR 
function converts a relative pointer to a pointer in order to reference 
the object of the relative pointer. 

The type of the object pointed to by the returned pointer is the same 
as the type of the object pointed to by the relative pointer. If the type 
of the parent variable associated with the specified relative pointer is 
not equivalent to the type of the specified parent variable, a compile- 
time error occurs. 

For further information on relative pointers, refer to Pointer Types in 
chanter 4. 
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$REAL Function 

The $REAL function returns the real number equivalent of a given 
integer expression. 

Use this format for the $REAL function call: 

$REAL(expression) 

expression 

An integer expression. 

#REL Function 

The #REL function returns a relative pointer. 
Use this format for the #REL function call: 
#REL(pointer_name {,parent_namej ) 

pointer _ name 

Name of the direct pointer variable. 

parent_name 

Name of the variable that contains the components being 
designated by relative pointers. If omitted, the default heap is 
used. The variable can be a string, array, record, heap, or 
sequence type (either fixed or adaptable). 

The type of the relative pointer's object is the same as the type of the 
given direct pointers object. (This type was specified in the "VAR 
declaration of the relative pointer variable.) The parent type of the 
relative pointer's object is the same as the type of the specified parent 
variable. 

If the pointer specified in the function call does not designate an 
element of the parent variable, the result is undefined. 

Relative pointer values can be generated solely through this function. 
For further information on relative pointers, refer to Pointer Types in 
chapter 4. 
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#Sn;y function 

The #SEQ function returns an adaptable pointer to a sequence 
allocated for a given variable. 

Use this format for the #SEQ function call: 

#SEQ(name) 

name 

Name of a variable of any type. 

The following relationships hold between the #LOC, #SEQ, and 
#SIZE functions: 

#LOC(#SEQ(name) * ) = #LOC(name) 

#SIZE(#SEQ(name) " ) = #SIZE(name) 
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#SIZE Function 

The #SIZE function returns the number of cells required to contain a 
given variable or a variable of a specified type. 

Use this format for the #SIZE function call: 

#SIZE(name) 

name 

Name of a variable, fixed record type, bound variant record, or 
an adaptable type. 

If you specify the name of a bound variant record type, the variant 
that requires the largest size is used. If you specify the name of an 
adaptable type, you must also supply a size fixer for the type. 

Example: 

The following example declares a procedure, FIND_SIZE, that has as 
its only parameter an adaptable array named A. An adaptable array 
type named B is also declared inside the procedure. When the 
procedure is called, the first #SIZE function determines the size of 
array A, the fixed array that was passed to it from the caller. The 
second #SIZE function determines the size of array B using a size 
fixer (the subrange is 1 to 100). 

PROCEDURE find_size (a: array [1 .. *] OF integer); 
VAR 

i: integer; 

TYPE 

b= array [1 .. *] of integer; 

i : = #SIZE(a) ; 

i := #SIZE(b: [1 .. 100]); 
PROCEND fincLsize; 
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STRLENGTH 

STRLENGTH Function 

The STRLENGTH function returns the length of a given string. 
Use this format for the STRLENGTH function call: 
STRLENGTH(string) 

string 

A string variable, name of a string type, or adaptable string 
reference. 

For a fixed string, the allocated length is returned as an integer 
subrange. For an adaptable string, the current length is returned. 

Example: 

The following example declares a procedure, FIND_LENGTH, that 
has as its only parameter an adaptable string named S. When the 
procedure is called, the STRLENGTH function determines the length 
of the fixed string that was passed to it. 

PROCEDURE fincLlength (s: string(*)) ; 
VAR i : integer; 

i := STRLENGTH (s); 
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succ 

SUCC Function 

The SUCC function returns the successor of a given expression. 
Use this format for the SUCC function call: 
SUCC(expression) 

expression 

A scalar expression. 

If the successor of the expression does not exist, the program is in 
error. 

Example: 

The following example declares two variables, HOT and COOL, each 
of which can take on ordinal values of the type SEASONS. The 
variable HOT is assigned the value SUMMER while the variable 
COOL is assigned the value FALL. 

TYPE 

seasons = (winter, spring, summer, fall); 

VAR 

hot : seasons , 
cool : seasons; 

hot := summer; 
cool := SUCC (hot); 
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UPPERBOUND 

UPPERBOUND Function 

The UPPERBOUND function returns the upper bound of an array's 
subscript bounds. 

Use this format for the UPPERBOUND function call: 

UPPERBOUND(array) 

array 

An array variable or the name of a fixed array type. 

The type of the value returned is the same as the type of the array's 
subscript bounds. 

Examples: 

Assuming the following declaration has been made 

VAR 

x: array [1 .. 100] of boolean, 

w ■ appau T'a' '+'1 nf intonon- 

the value of UPPERBOUND(X) is 100; the value of UPPERBOUND(Y) 

is Y. 

In the following example, the value of UPPERBOUND(TABLE) is 50: 

VAR 

table: 'array [1 .. * ] of cell; 

ALLOCATE table: [1 .. 50]; 



Revision F Functions 6-13 



UPPERVALUE 

UPPERVALUE Function 

The UPPERVALUE function returns the largest possible value that a 
given variable or type can have. 

Use this format for the UPPERVALUE function call: 

UPPERVALUE(name) 

name 

A scalar variable or name of a scalar type. 

The type of the value returned is the same as the given type. 

Examples: 

Assuming the following declaration has been made 

VAR 

dozen: 1 .. 12; 

the value of UPPERVALUE (DOZEN) is 12. 

After the declarations 

TYPE 

t = (first, second, third); 

VAR 
V: t; 

the value of UPPERVALUE(V) is THIRD and the value of 
UPPERVALUE(T) is THIRD. 
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User-Defined Functions 

This section describes how you define your own functions. 

Function Declaration 

You define your own function with the function declaration. 
Use this format to declare a function: 

FUNCTION {[attributes]} name {(formal ..parameters)} : 

result.type; 1 

{declaration _ list;} 
statement_Iist; 
FUNCEND {name} ; 

attributes 

One or more of the following attributes. If you specify more 
than one, separate them with commas. 

XREF 

The function has been compiled in a different module. In 
this case, the function declaration can contain the name and 
formal parameters, but no declaration list or statement list. 
In the other module, the function must have been declared 
with the XDCL attribute and an identical parameter list. If 
omitted, the function must be defined within the module 
where it is called. 

XDCL 

The function can be called from outside of the module in 
which it is located. This attribute can be included only in a 
function declared at the outermost level of a module; it 
cannot be contained in a program, procedure, or another 
function. Other modules that call this function must contain 
the same function declaration with the XREF attribute 
specified. 



1. Some variations of CYBIL available on other operating systems allow an additional 
option, the alias name, in a function declaration. If included in a CYBIL program run 
on NOS/VE, this parameter is ignored. 
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Function Declaration 



INLINE 



Instead of calling the function, the compiler inserts the 
actual function statements at the point in the code where 
the function call is made. Additional information on inline 
functions is given later in this section. 

#GATE 2 

The function can be called by a function call from a higher 
ring level if the call is issued from within the call bracket 
of the gated function. 3 If you specify #GATE, you must also 
specify the XDCL attribute. 

If you don't specify any attributes, the function is assumed to 
be in the same module in which it is called. 

name 

Name of the function. The function name is optional following 
FUNCEND. 

formal_parameters 

One or more parameters in the form: 

VAR name {,name}... : type 
{,name {,namej... : type}... 

and/or: 

name {,name}... : type 

{,name {,name}... : type}... 

The first form is called a reference parameter; the second form 
is called a value parameter. There is essentially no difference 
between them in the context of a function. However,, procedures 
(and programs) do treat them differently. Both kinds of 
parameters can appear in the formal parameter list; if so, they 
are separated by semicolons (for example, [LINTEGER; VAR 
A:CHAR). Reference and value parameters are discussed in 
more detail later in this chapter under Parameter List. 

The maximum number of parameters that can be passed to an 
externally referenced (XREF) function is" 126. 



2. This attribute is not supported on variations of CYBIL available on other operating 
systems. 

3. A ring level is a hardware feature. Rings provide hardware protection in that an 
unauthorized program cannot access anything at a lower ring level. For further 
information on rings, refer to the SCL Object Code Management manual. 
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Function Declaration 



i es uit _ type 

The type of the result to be returned. Specify any fixed scalar, 
floating-point, pointer, or cell type. 

declaration^ list 

Zero or more declarations. 

statement .list 

One or more statements. 

In an assignment statement within a function, the lefthand side of the 
statement (the variable to receive the value) cannot be: 

• A nonlocal variable. 

• A formal parameter of the function. 

• The object of a pointer variable. 
User-defined functions cannot contain: 

• Procedure call statements that call user-defined procedures or 
NOS/VE procedures. 

• Parameters of type pointer to procedure. 

• ALLOCATE, FREE, PUSH, or NEXT statements that have 
parameters that are not local variables. 
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Parameter List 

A parameter list is an optional list of variable declarations that 
appears in the first statement of the function declaration. In the 
function declaration format shown earlier, they are shown as formal., 
parameters. Declarations for formal parameters must appear in that 
first statement; they cannot appear in the declaration list in the body 
of the function. 

A parameter list allows you to pass values from the calling program 
to the function. When a call is made to a function, parameters called 
actual parameters are included with the function name. The values of 
those actual parameters replace the formal parameters in the 
parameter list. Wherever the formal parameters exist in the 
statements within the function, the values of the corresponding actual 
parameters are substituted. For every formal parameter in a function 
declaration, there must be a corresponding actual parameter in the 
function call. 

There are two kinds of parameters: reference parameters and value 
parameters. A reference parameter has the form: 

VAR name {,name}... : type 
{,name {,rvame}... : type}... 

A value parameter has the form: 

name {,namej... : type 

{,name {,name}... : type}... 
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Parameter List 

In procedures, reierenee parameters and value parameters cause 
different actions to be taken; in functions, however, both kinds of 
parameters have the same effect. (In a procedure, the value of a 
reference parameter can change during execution of the procedure; a 
value parameter cannot change.) In a function, neither reference 
narameters nor value parameters can change in value. A formal 
reference parameter can be any fixed or adaptable type. A formal 
value parameter can be any fixed or adaptable type, except a heap or 
an array or record that contains a heap. 

Reference parameters and value parameters can be specified in many 
combinations. When both kinds of parameters appear together, they 
must be separated by semicolons. Parameters of the same type can 
also be separated by semicolons instead of commas, but in this case, 
VAR must appear with each reference parameter. All of the following 
parameter lists are valid. 

• VAR i, j: integer; a, b: char; 

• VAR i: integer; VAR j: integer; a: char; b: char; 

A 9 ■ r*Hgn • WAD 4 4 • 1 nfgnon ■ K . nh^ar . 

— ss. . onGi , vrti* i , j . in i,w^£i , i_; . viiCii , 

• VAR i: integer, j: real; a: char, b: boolean; 

In each of the preceding examples, I and J are reference parameters; 
A and B are value parameters. 
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Referencing a Function 

The call to the function is usually contained in an expression. The 
call consists of the function name (as given in the function 
declaration) and any parameters to be passed to the function in the 
following format: 

name ({actual ^parameters} ) 

name 

Name of the function. 

actual _parameters 

Zero or more expressions or variables to be substituted for 
formal parameters defined in the function declaration. If you 
specify two or more, separate them with commas. They are 
substituted one-for-one based on their position within the list; 
that is, the first actual parameter replaces the first formal 
parameter, the second actual parameter replaces the second 
formal parameter, and so on. For every formal parameter in a 
function declaration, there must be a corresponding actual 
parameter in the function call. 

If you did not specify any formal parameters in the function 
declaration, you can't include any actual parameters in the 
function call. However, you must enter left and right 
parentheses to indicate the absence of parameters. In this case, 
the call is: 

name( ) 

The function can be anywhere that a variable of the same type could 
be. The value returned by a function is the last value assigned to it. 
If control is returned to the calling point before an assignment is 

maA& racnlfc oro iir»rM-o^i/>foV»1p 

The only types that can be returned as values of functions are the 
basic types: scalar, floating point, pointer, and cell. 
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Referencing a Function 



m_. 



j_jXfuiipie: 



The following function finds the smaller of two integer values 
represented by formal value parameters A and B. The smaller value 
is assigned to MIN, the name of the function, and that integer value 
is returned. 

FUNCTION min (a, 

b: integer): integer; 
IF a > b THEN 

min := b; 
ELSE 

min := a; 
I FEND; 
FUNCEND min; 

This function could be called using the following reference: 

smaller : = min (first, second); 

The value of the variable FIRST is substituted for the formal 
parameter A; the value of SECOND is substituted for B. The value 
returned, the smaller value, replaces the entire function reference; the 
variable SMALLER is assigned the smaller value. 
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Inline Functions 

An inline function is one for which the compiler inserts the actual 
statements that are within the function at the point in the code where 
the function call was made. An inline function must be declared with 
the INLINE attribute. (Procedures can also be declared to be inline.) 

Type, constant, and variable declarations that are local to an inline 
function or procedure are appended to the declarations of the function 
or procedure that called it. However, these types, constants, and 
variables can be referenced only within the body of the inline function 
or procedure; all the usual naming rules and scope rules still apply. 
(Local variable declarations in an inline function or procedure become 
part of the stack frame of the calling procedure.) 

A variable declared within an inline function or procedure cannot be 
declared with the STATIC or XDCL attribute. Another function or 
procedure can be declared within an inline function or procedure only 
if it is declared with the XREF (externally declared) attribute; an 
inline function or procedure cannot contain any other function or 
procedure declarations. 

Formal parameters in an inline function or procedure are treated as 
local variable declarations. When an inline function or procedure is 
called, the actual parameters are assigned to the corresponding formal 
parameters' local variables. Reference parameters are accessed by 
assigning a pointer to the actual parameter to the formal parameter's 
local variable. 

When the actual parameter for a value parameter is an adaptable 
type or a substring, the parameter is treated as a read-only reference 
parameter (that is, a local copy of the parameter is not created). This 
is necessary to allow the type to be set at execution time. For 
adaptable array and adaptable record value parameters, the actual 
parameter must ue oyte-aiigned. 
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Inline Functions 
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procedure, including other inline functions and procedures, up to five 
levels. However, recursive calls to an inline function or procedure, 
either directly or indirectly, are not allowed. More than five nested 
calls and recursive calls are considered compile-time errors and end 
inline substitution. 

Space that is allocated by a PUSH statement in an inline function or 
procedure is not released until the calling (not the inline) function or 
procedure completes. 

The result of a reference to an inline function becomes part of the 
caller's stack frame. When an inline function is called more than once 
within a statement, the results of each reference are separate even 
though they share the same name. 

The name of an inline function or procedure cannot be used in a 
pointer reference. 

If a source listing is produced during compilation, the statements of 
the inline function or procedure are not listed at the point where the 



nw»nrc 



You can use the Debug Utility with inline functions and procedures. 
Debug treats an inline procedure call as a series of statements on the 
same line as the procedure call itself. It treats an inline function call 
as a series of statements on the same line as the end of the phrase 
that contained the reference to the inline function. Debug may not be 
able to access local variables declared in an inline function or 
procedure directly because the substitution process could create 
duplicate variable names (for example, if the names have already been 
used in the calling function or procedure). In that case, the Debug 
Utility always gives precedence to the variable names used in the 
calling procedure. For further information on the Debug Utility, refer 
to chapter 9. 
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System-Dependent Functions 

The functions described here can be used with CYBIL only on 
NOS/VE. As you review this section, keep in mind that programs 
using these functions cannot be transported to other operating systems 
and run on variations of CYBIL. 

To use these functions properly and efficiently, you should be familiar 
with basic hardware concepts of your computer system. This 
information can be found in volume II of the virtual state hardware 
reference manual. 

The functions are described in alphabetical order. 
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#ADDRESS 

# ADDRESS Function 

The #ADDRESS function accepts a ring number, segment number, 
and byte offset and returns a value that is of type pointer to cell. 

Use this format for the #ADDRESS function call: 

#ADDRESS(ring, segment, offset) 

ring 

Ring number, ranging from 1 to 15. 

segment 

Segment number, ranging from to 4,095. 

offset 

Byte offset, ranging from -80000000 hexadecimal to 7FFFFFFF 
hexadecimal. 

Example: 

The following example uses the #ADDRESS function to set the 
variable PTR1 to a pointer to cell formed using a ring number of 11, 
a segment number of 10, and a byte offset of 0FFFF hexadecimal. 



VAR 






i , 






J, 






k: 


integer, 




Pt 


n 1 ; * ce 1 1 ; 


i 


; = 


11; 


J 


: = 


10; 


k 


: = 


0ffff(16); 



ptM := ^address (i, j, k); 
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#FREE_RUNNING .CLOCK Function 

The #FREE_RUNNING_CLOCK function returns the value of the 
free running microsecond clock. 

Use this format for the #FREE_RUNNING_CLOCK function call: 

#FREE_RUNNING_CLOCK(port) 

port 

An integer expression whose value is or 1. It specifies the 
memory port to be used for reading the clock. 

The integer value returned is that of the free running clock that is 
maintained within the memory connected to the specified processor 
memory port. 

For further information on the free running microsecond clock and 
memory ports, refer to volume II of the virtual state hardware 
reference manual. 

Example: 

The following example sets the integer variable I to the value of the 
free running microsecond clock in the memory connected to processor 
memory port 0. 

VAR 

i: integer; 

i := #free_running_c1ock (0); 
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#OFFSET Function 

The #OFFSET function accepts a pointer and returns the integer 
value of the signed offset (byte number) contained in the pointer. 

Use this format for the #OFFSET function call: 

#OFFSET(pointer) 

pointer 

Name of a pointer expression. 

A pointer consists in part of the process virtual address (PVA) of the 
first byte of the object to which it is pointing. An element of the PVA 
is the byte number. This byte number is the signed offset returned. 

For further information on PVAs, refer to volume II of the virtual 
state hardware reference manual. 

Example: 

The following example finds the b u te offset in the r *ointer PTftl 

VAR 

ptrl: "cell, 

byte.of f set : - 80000000(16) .. 7fffffff (16); 

byte_offset := Soffset (ptrl); 
If PTR1 was formed using the following #ADDRESS function, 

ptrl := #address (11, 10, 0ffff(16)); 
the value of BYTE_OFFSET would be 0FFFF hexadecimal. 
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#PRE VIOUS _ SAVE _ ARE A Function 

the #PREVIOUS_SAVE_AREA function returns a pointer to the first 
cell of the previous save area. 

Use this format for the #PREVIOUS_SAVE_AREA function call: 

#PREVIOUS_ SAVE _ AREA ( ) 

A procedure uses an area called a stack frame to store its automatic 
variables. If another procedure is called, hardware saves certain 
registers of the calling procedure and puts them in a stack frame save 
area. These registers contain the information required for the calling 
procedure to resume normal execution when control is returned by the 
called procedure. 

If procedure calls are nested, each subsequent call creates its own 
stack frame save area and the last save area becomes the previous 
save area. Pointers are kept to link the previous save areas so that as 
procedures complete and return, the system works back through the 
previous save areas using the information contained in them to 
resume each procedure. 

The formats of the stack frame save area and previous save area are 
shown in the CYBIL System Interface manual. For further information 
on the stack frame save area and previous save area, refer to volume 
II of the virtual state hardware reference manual. 
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#PREVIOUS_SAVE AREA 



jcjxampie: 

The following example sets the pointer variable PSA_PTR to point to 
the first cell of the previous save area. The #CALLER_ID procedure 
then returns information about the caller of the last function. That 
information is returned in the record CALLER_RECORD. In this 
example, CALLER_ RECORD is equivalent to the object of pointer 
PSA_PTR (that is, CALLER_RECORD = PSA_PTR*). 

TYPE 

id_rec = record 

id: .. 0ffffffff(16), 
recend; 

VAR 

psa_ptr: *id_rec, 
caller_record: id_rec; 

psa_ptr := #prev1ous_save_area (); 
#caller_1d (cal ler_record) ; 
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#READ .REGISTER Function 

The #READ_REGISTER function performs actions equivalent to the 
copy from state register (CPYSX) hardware instruction. It allows a 
program to read the contents of a process or processor register. 

Use this format for the #READ_ REGISTER function call: 

#READ _ REGISTER(register _id) 

register_id 

An integer expression from to 255 that identifies the number 
of the register to be read. Register numbers are given in 
volume II of the virtual state hardware reference manual. 

An integer value is returned. 

The #WRITE_REGISTER procedure described in chapter 7 allows a 
program to change the contents of a process or processor register. 

For further information on process and processor registers, and the 
CPYSX instruction, refer to volume II of the virtual state hardware 
reference manual. 

Example: 

The following example sets the integer variable J to the value of 
register E5, the Debug mask register. 

VAR 

j: integer; 

j := #read_register (0e5(16)); 
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#RING 

#RING Function 

The #RING function accepts a pointer and returns the integer value 
of the ring number contained in the pointer. 

Use this format for the #RING function call: 

#RING(pointer) 

pointer 

Name of a pointer expression. 

Example: 

The following example finds the ring number in the pointer PTR1. 

VAR 

ptM: "cell, 
ring_number: integer; 

ring_number := #ring (ptM); 
If PTR1 was formed using the following #ADDRESS function, 

ptM := #address (11, 10, 0ffff(16)),- 
the value of RING_NUMBER would be 11. 
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#SEGMENT Function 

The #SEGMENT function accepts a pointer and returns the integer 
value of the segment number contained in the pointer. 

Use this format for the #SEGMENT function call: 

#SEGMENT(pointer) 

pointer 

Name of a pointer expression. 

Example: 

The following example finds the segment number in the pointer PTR1. 

VAR 

ptrl: "cell, 

segment .number : i nt eger : 

segment _number := #segment (ptrl); 
If PTR1 was formed using the following #ADDRESS function, 

ptM := #address (11, 10, 0ffff(16)); 
the value of SEGMENT. NUMBER would be 10. 
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This chapter describes the procedures that are predefined in CYBIL 
and explains how you can define your own procedures. 
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#CONVERT_POINTER_TO_PROCEDURE Procedure 7-25 

#HASH_SVA Procedure 7-26 

#KEYPOINT Procedure 7-27 
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#SCAN Procedure 7-30 

#SPOIL Procedure 7-32 

^TRANSLATE Procedure 7-34 

#UNCHECKED_CONVERSION Procedure 7-35 

#WRITE_REGISTER Procedure 7-37 



Procedures 



A procedure is one or more statements that perform a specific action 
and can be called by a single statement. A procedure allows you to 
associate a name with the statement list so that by specifying the 
name itself as if it were a statement, you cause the list to be 
executed. Declarations can be included and take effect when the 
procedure is called. A procedure call can optionally cause actual 
parameters included in the call to be substituted for the formal 
parameters in the procedure declaration before the procedure's 
statements are executed. 

A procedure differs from a function in that: 

• A procedure can, but does not always, return a value. 

• The call to a procedure is the procedure's name itself; a function 
call by contrast must be part of an expression in a statement. 

• There can be no value assigned to the procedure name as there is 
to a function name. 

Procedures can be recursive; that is, a procedure can call itself. In 
that case, the code within the procedure must not modify itself. 
Appendix F, The CYBIL Run-Time Environment, describes how 
recursive procedures are managed. 

You can call standard procedures that are already defined in the 
CYBIL language, you can define your own procedures, or you can call 
procedures designed specifically for use on NOS/VE. This chapter 
describes all three. 
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Standard Procedures 

The STRINGREP procedure described here is a standard CYBIL 
procedure. It can be used safely in variations of CYBIL available on 
other operating systems. The last section in this chapter, 
System-Dependent Procedures, describes procedures that may not be 
available on other operating systems or that are unique to CYBIL on 
NOS/VE. 

STRINGREP Procedure 

The STRINGREP procedure converts one or more elements to a string 
of characters, then returns that string and the length of the string. 

Use this format for the STRINGREP procedure call: 

STRINGREP(string_name, length, element {,element}..>, 

string _ name 

Name of a string type variable. (You can specify it as a 
substring.) The result is returned here. It will contain the 
character representations of the named element(s). 

length 

Name of an integer variable. The procedure will set its value 
to the length in characters of the resulting string variable, 
string_name. It will be less than or equal to the declared 
length of the string variable. 

element 

Name of the element to be converted. The element can be a 
scalar, floating-point, pointer, or string type. Formats for 
specifying particular types and rules for conversion of those 
types are discussed in more detail later in this chapter. 
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STRINGREP 



ine namea elements are converted to strings 01 cnaracters. rnose 
strings are then concatenated and returned left-justified in the named 
string variable. The length of the string variable is also returned. If 
the result of concatenating the string representations is longer than 
the length of the string variable, the representation of the last 
element is a string of asterisk characters; the length that will be 
returned is the length of the string variable. 

Each individual element is converted and placed in a temporary field 
before concatenation with other elements. The length of the temporary 
field can be specified as part of the element parameter that is 
described in the following sections. Generally, numeric values are 
written right-justified in the temporary field with spaces added on the 
left to fill the field, if necessary. String or character values are 
written left-justified in the temporary field with spaces added on the 
right to fill the field, if necessary. For both numeric and alphabetic 
values, the field is filled with asterisk characters if it is too short to 
hold the resulting value. The value of the field length, when specified, 
must be greater than or equal to zero; otherwise, an error occurs. 

The following paragraphs describe how the STRINGREP procedure 
converts specific types and how they appear in the temporary fields. 
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Integer Element 

Use this format to specify an integer element: 
expression / ; length } { : #(radix) } 

expression 

An integer expression to be converted. 

length 

A positive integer expression specifying the length of the 
temporary field. The length must be greater than or equal to 2. 
If it is omitted, the temporary field is the size required to hold 
the integer value and the leading sign character. 

radix 

Radix of expression. Possible values are 2, 8, 10, and 16. If it 
is omitted, 10 is assumed. 

The value of the integer expression is converted into a string 
representation in the desired radix. The resulting string representation 
is right-justified in the temporary field. If the expression is positive, a 
space precedes the leftmost significant digit. If the integer expression 
is negative, a minus sign precedes the leftmost significant digit. The 
leading space or hyphen must be considered a part of the length. 
Thus, the length must be greater than or equal to 2 in order to hold 
the sign character and at least one digit. 

If you specify a field length larger than necessary, spaces are added 
on the left to fill the field. If you specify a field length that is not 
long enough to contain all digits and the sign character, the field is 
filled with a string of asterisk characters. If you specify a field length 
less than or equal to zero, an error occurs. 
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Use this format to specify a character element: 
expression / ; length } 

expression 

A character expression to be converted. 

length 

A positive integer expression specifying the length of the 
temporary field. If it is omitted, a length of 1 is assumed. 

A single character is left-justified in the temporary field. If you 
specify a field length larger than necessary, spaces are added on the 
right to fill the field. Including a radix for a character element causes 
a compilation error. 

Boolean Element 

Use this format to specify a boolean element: 
expression { : length } 

expression 

A boolean expression to be converted. 

length 

A positive integer expression specifying the length of the 
temporary field. If it is omitted, a length of 5 is assumed. 

Either of the 5-character strings ' TRUE' or 'FALSE' is left-justified in 
the temporary field. If you specify a field length larger than 
necessary, spaces are added on the right to fill the field. If you 
specify a field length that is not long enough to contain all five 
characters, the temporary field is filled with asterisk characters. 
Likewise, if the expression you supply is neither TRUE nor FALSE, 
the temporary field is filled with asterisk characters. Including a radix 
for a boolean element causes a compilation error to occur. 
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Ordinal Element 

The integer value of an ordinal expression is handled the same way 
as an integer element. Refer to the discussion under Integer Element 
earlier in this chapter. 

Subrange Element 

A subrange element is handled the same way as the element of which 
it is a subrange. 

Floating-Point Element 

Use this format to specify a floating-point element: 
expression { : length { : fraction } } 

expression 

A real expression to be converted. If the value is INFINITE or 
INDEFINITE, an error occurs. 

length 

A positive integer expression specifying the length of the 
temporary field. If it is omitted, the temporary field is the size 
required to hold the real value and the necessary leading 
character. 

fraction 

Positive integer expression specifying the number of fractional 
digits to be included in a fixed-point, format. Specify a value 
less than or equal to "length - 2". If it is omitted, conversion 
to floating-point format is assumed. 

A floating-point expression can be converted into either a fixed-point 
format or a floating-point format depending on the fraction parameter. 
If it is included, the expression is converted to fixed-point format; if it 
is omitted, the expression is converted to floating-point format. 
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The form 

expression {: length{: fraction}} 

causes the specified expression to be converted to a string in 
fixed-point format. The string will have the specified length with the 
specified number of fractional digits to the right of the decimal place. 
The expression is rounded off so that the specified number of 
fractional digits are present. If no positive digit appears to the left of 
the decimal point, a (zero) is inserted. 

When figuring the length required to hold the expression, the compiler 
counts all digits to the left of the decimal point (it also counts if it 

apical o aiuiic/, unc ucuiitiai pvl-Liit, anu wuO opci.Ju.xcu lluiTiUCl Ul 

fractional digits that appear to the right of the decimal point. If the 
expression is negative, an extra space is required for the minus sign. 
If you specify a field length larger than necessary, spaces are added 
on the left to fill the field. If you specify a field length that is not 
long enough to contain all digits, the sign character, and the decimal 

pViiiv, WiC il&IU i.iJ iXiiw^A Y»ii,ii CL ObX.Li..lg£ \JX fJLo LCI. ±&Hk. \j!.i.CLi. €X\s LCi. O. 

Examples: 

Value of Format of 

Expression E Element Resulting String 

1.23456 E:6:2 ' 1.23' 

-1.23456 E:6:3 '-1.235' 

E:5:2 ' 0.00' 
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Floating-Point Format 

The form 

expression {: length} 

causes the specified expression to be converted to a string in 
floating-point format. 

The length of the temporary field is determined somewhat differently 
from the other elements. The system defines a maximum number of 
digits that can be contained in the mantissa of a real number and the 
number of digits that can be in the exponent. 

When the compiler figures the number of digits that will be in the 
mantissa, it first determines the number of spaces that must be 
present in the string. It allows for the number of digits in the 
exponent and four additional spaces: one for the sign of the expression 
(a space if positive, - if negative), one for the decimal point in the 
mantissa, one for the exponent character (E), and one for the sign of 
the exponent (+ or -). The total number of required spaces is 
subtracted from the specified field length. The compiler then compares 
the result (field length minus required spaces) and the maximum 
number of digits allowed in the mantissa, and takes the smaller of 
the two. That number is used as the number of digits in the mantissa 
when the compiler rounds the floating-point expression. 

If a field length larger than necessary is specified, spaces are added 
on the left to fill the field. If the fixed size of the exponent is larger 
than necessary, zeroes are added on the left to fill the field. If the 
number that results from the subtraction of required spaces from the 
field length is less than 1, the field is filled with a string of asterisk 
characters. 



tixamples: 

Value of 
Expression E 


Format of 
Element 


Resulting String 


123.456 
-123.456 


E:10 
E:ll 


' 1.23E+002' 
'-1.235E+002' 
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Use this format to specify a pointer element: 
pointer { : length } { : #(radix) } 

pointer 

A pointer reference to be converted. 

length 

A positive integer expression specifying the length of the 
temporary field. If you omit the field length, the temporary 
field is the size required to contain the pointer value. 

radix 

Radix of the pointer value. Possible values are 2, 8, 10, and 
16. For NOS/VE, the default radix is 16. 

The value of the pointer expression is converted into a string 
representation in the specified radix. It is right-justified in the 
temporary field. If you specify a field length larger than necessary, 
spaces are added on the left to fill the field. If you specify a field 
length that is not long enough to contain all the digits, the field is 
filled with a string of asterisk characters. 

String Element 

Use this format to specify a string element: 
expression ( ; length / 

expression 

A string variable, string constant, or substring to be converted. 

length 

A positive integer expression specifying the length of the 
temporary field. If it is omitted, the field is the size required 
to contain the string expression. 

A string expression is left-justified in the temporary field. If you 
specify a field length larger than necessary, spaces are added on the 
right to fill the field. If you specify a field length that is shorter than 
the length of the string, the temporary field is filled with a string of 
asterisk characters. 
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User-Defined Procedures 

This section describes how you define your own procedures. 

Procedure Declaration 

You define your own procedure with the procedure declaration. 
Use this format to declare a procedure: 

PROCEDURE {[attributes]} name {(formal _parameters)}i L 

{declaration^ list;} 

{statement _ list;} 
PROCEND {name} ; 

attributes 

Specify one or more of the following attributes. If you specify 
more than one attribute, separate them with commas. 

XREF 

The procedure has been compiled in a different module. In 
this case, the procedure declaration can contain the name 
and formal parameters, but no declaration list or statement 
list. In the other module, the procedure must have been 
declared with the XDCL attribute and an identical 
parameter list. If it is omitted, the procedure must be 
defined within the module where it is called. 

XDCL 

*«v piu^vuuiL> v-m.*j. Kfu i^tLxivu 11U1U UULOlUC UL1C illUUUJC J.I1 

which it is located. This attribute can be included only in a 
procedure declared at the outermost level of a module; it 
cannot be contained in a program, function, or another 
procedure. Other modules that call this procedure must 
contain the same procedure declaration with the XREF 
attribute specified. 



1. Some variations of CYBIL available on other operating systems allow an additional 
option, the alias name, in a procedure declaration. If it is included in a CYBIL 
program run on NOS/VE, this parameter is ignored. 
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User-Defined Procedures 



Instead of calling the procedure, the compiler inserts the 
actual procedure statements at the point in the code where 
the procedure call is made. Additional information on inline 
procedures is given later in this section. 

#GATE 2 

The procedure can be called by a procedure at a higher 
ring level if the call is issued from within the call bracket 
of the gated procedure. 3 If you specify #GATE, you must 
also specify the XDCL attribute. 

If you don't specify any attributes, the procedure is assumed to 
be in the same module in which it is called. 

name 

Name of the procedure. The procedure name is optional 
following PROCEND. 

formal_parameters 

One or more parameters in the form! 

VAR name {,name}... : type 
{,name {,name}... : type}... 

and/or: 



name {,name}... : type 

{,name {,name}... : type}... 



2. This attribute is not supported on variations of CYBIL available on other operating 
systems. 

3. A ring level is a hardware feature. Rings provide hardware protection in that an 
unauthorized program cannot access anything at a lower ring level. For further 
information on rings, refer to the SCL Object Code Management manual. 
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The first form is called a reference parameter; its value can be 
changed during execution of the procedure. The second form is 
called a value parameter; its value cannot be changed by the 
procedure. Both kinds of parameters can appear in the formal 
parameter list; if so, separate them with semicolons (for 
example, LINTEGER; VAR A:CHAR). Reference and value 
parameters are discussed in more detail later in this chapter 
under Parameter List. 

The maximum number of parameters that can be passed to an 
externally referenced (XREF) procedure is 127. 

declaration_list 

Zero or more declarations. 

statement _list 

Zero or more statements. 

The maximum number of user-defined procedures allowed in a single 
compilation unit is 999. Procedures can be nested up to 50 levels. 
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User-Defined Procedures 



rarameter L,ist 

A parameter list is an optional list of variable declarations that 
appears in the first statement of the procedure declaration. In the 
procedure declaration format shown earlier, they are shown as 
formal _parameters. Declarations for formal parameters must appear in 
that first statement; they cannot appear in the declaration list in the 
body of the procedure. 

A parameter list allows you to pass values from the calling program 
to the procedure. When a call is made to a procedure, parameters 
called actual parameters are included with the procedure name. The 
values of those actual parameters replace the formal parameters in 
the parameter list. Wherever the formal parameters exist in the 
statements within the procedure, the values of the corresponding 
actual parameters are substituted. For every formal parameter in a 
procedure declaration, there must be a corresponding actual parameter 
in the procedure call. 

There are two kinds of parameters: reference parameters and value 
parameters. A reference parameter has the form: 

VAR name {,name}... : type 
{,name {,name}... : type}... 

When a reference parameter is used, the formal parameter represents 
the corresponding actual parameter throughout execution of the 
procedure. Thus, an assignment to a formal parameter changes the 
variable that was passed as the corresponding actual parameter. An 
actual parameter corresponding to a formal reference parameter must 
be addressable. A formal reference parameter can be any fixed or 
adaptable type. If the formal parameter is a fixed type, the actual 
parameter must be a variable or substring of an equivalent type. If 
the formal parameter is an adaptable type, the actual parameter must 
be a variable or substring whose type is potentially equivalent. (For 
further information on potentially equivalent types, refer to Equivalent 
Types in chapter 4.) 

A value parameter has the form: 

name {,namej... : type 

{,name {,name}... : type}... 
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When a value parameter is used, the formal parameter takes on the 
value of the corresponding actual parameter. However, the procedure 
cannot change a value parameter by assigning a value to it or using 
it as an actual reference parameter to another procedure or function. 
A formal value parameter can be any fixed or adaptable type except a 
type that cannot have a value assigned, that is, a heap, or an array 
or record that contains a heap. If the formal parameter is a fixed 
type, the actual parameter can be any expression that could be 
assigned to a variable of that type. Strings must be of equal length. If 
the formal parameter is an adaptable type, the current type of the 
actual parameter must be one to which the formal parameter can 
adapt. If the formal parameter is an adaptable pointer, the actual 
parameter can be any pointer expression that could be assigned to the 
formal parameter. Both the value and the current type of the actual 
parameter are assigned to the formal parameter. 

Reference parameters and value parameters can be specified in many 
combinations. When both kinds of parameters appear together, they 
must be separated by semicolons. Parameters of the same type can 
also be separated by semicolons instead of commas, but in this case, 
VAR must appear with each reference parameter. All of the following 
parameter lists are valid: 

• VAR i, j: integer; a, b: char; 

• VAR i: integer; VAR j: integer; a: char; b: char; 

• a: char; VAR i, j: integer; b: char; 

• VAR i: integer, j: real; a: char, b: boolean; 

In each of the preceding examples, I and J are reference parameters; 
A and B are value parameters. 
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Calling a Procedure 

A call to a procedure consists of the procedure name (as given in the 
procedure declaration) and any parameters to be passed to the 
procedure in the following format: 

name {(actual _parameters)} ; 

name 

Name of the procedure or a pointer to a procedure. 

actual _parameters 

One or more expressions or variables to be substituted for 
formal parameters defined in the procedure declaration. If you 



substituted one-for-one based on their position within the list; 
that is, the first actual parameter replaces the first formal 
parameter, the second actual parameter replaces the second 
formal parameter, and so on. For every formal parameter in a 
procedure declaration, there must be a corresponding actual 
Parameter in the procedure call. 

A procedure is a type, like the types described in chapter 4. Procedure 
types are used for declaration of pointers to procedures; there are no 
procedure variables. 

The lifetime of a formal parameter is the lifetime of the procedure in 
which it is a part. Storage space for the parameter is allocated when 
the procedure is entered and released when the procedure is left. 

The lifetime of a variable that is allocated using the storage 
management statements (described in chapter 5) is the time between 
the allocation of storage (with the ALLOCATE statement) and the 
release of storage (with the FREE statement). 

Two procedure types are equivalent if corresponding parameter 
segments have the same number of formal parameters, the same 
methods of passing parameters (reference or value), and equivalent 
types. 
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Example: 



This example calculates the greatest common divisor X of M and N. 
M and N are passed as value parameters; that is, their values are 
used but M and N themselves are not changed. X, Y, and Z are 
reference parameters (preceded by the VAR keyword). Their original 
values are not used in this procedure; they are assigned new values 
in the procedure that destroy their previous values. 



PROCEDURE 


gcd (m, 






n: 


integer; 






VAR x. 








y, 








Z: 


integer) ; 






{Extended 


Euclid's 


Algor 


thm} 


VAR 








al, 








a2, 








ul , 








D2, 








c, 








d, 








q, 








r: integer; 







a1 


= o, 


a2 


= 1; 


bl 


= 1; 


b2 


= 0; 



C := m; 

H . = n . 
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User-Defined Procedures 



{a1 * m + b1 * n = d, a2 * m + b2 * n = c} 
{gcd (c,d) = gcd (m,n)} 

q := c DIV d; 

r := C MOD d; 

a2 := a2 - q * a1; 
q * b1; 





b2 


:= b2 




c 


= d; 




d 


= n • 




r 


= a1; 




a1 


:= a2 




a2 


:= T; 




r 


= b1; 




b1 


:= b2 




b2 


:= r; 


WHILEND; 


X 


: = 


C; 


y 


: = 


32; 


z 


: = 


b2; 



{x = gcd (m,n), y*m+z*n= gcd (m,n)} 
PROCEND gcd; 
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Inline Procedures 

An inline procedure is one for which the compiler inserts the actual 
statements that are within the procedure at the point in the code 
where the procedure call was made. An inline procedure must be 
declared with the INLINE attribute. (Functions can also be declared 
to be inline.) 

Type, constant, and variable declarations that are local to an inline 
function or procedure are appended to the declarations of the function 
or procedure that called it. However, these types, constants, and 
variables can be referenced only within the body of the inline function 
or procedure; all the usual naming rules and scope rules still apply. 
(Local variable declarations in an inline function or procedure become 
part of the stack frame of the calling procedure.) 

A variable declared within an inline function or procedure cannot be 
declared with the STATIC or XDCL attribute. Another function or 
procedure can be declared within an inline function or procedure only 
if it is declared with the XREF (externally declared) attribute; an 
inline function or procedure cannot contain any other function or 
procedure declarations. 

Formal parameters in an inline function or procedure are treated as 
local variable declarations. When an inline function or procedure is 
called, the actual parameters are assigned to the corresponding formal 
parameter's local variables. Reference parameters are accessed by 
assigning a pointer to the actual parameter to the formal parameter's 
local variable. 

When the actual parameter for a value parameter is an adaptable 
type or a substring, the parameter is treated as a read-only reference 
parameter (that is, a local copy of the parameter is not created). This 
is necessary to allow the type to be set at execution time. For 
adaptable array and adaptable record value parameters, the actual 
parameter must be byte-aligned. 

An inline function or procedure can call any other function or 
procedure, including other inline functions and procedures, up to five 
levels. However, recursive calls to an inline function or procedure, 
either directly or indirectly, are not allowed. More than five nested 
calls and recursive calls are considered compile-time errors and end 
inline substitution. 
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Inline Procedures 

Space that is allocated by a PUSH statement in an inline function or 
procedure is not released until the calling (not the inline) function or 
procedure completes. 

The result of a reference to an inline function becomes part of the 
caller's stack frame. When an inline function is called more than once 
within a statement, the results of each reference are separate even 
though they share the same name. 

The name of an inline function or procedure cannot be used in a 
pointer reference. 

If a source listing is produced during compilation, the statements of 
the inline function or procedure are not listed at the point where the 
call occurs. 

You can use the Debug Utility with inline functions and procedures. 
Debug treats an inline procedure call as a series of statements on the 
same line as the procedure call itself. It treats an inline function call 
as a series of statements on the same line as the end of the phrase 
that contained the reference to the inline function. Debug may not be 

„ui„ *-„ „„„ i„_„i ..„_;„i,i j„~i j ;_ ;_14 «. „^ 

procedure directly because the substitution process could create 
duplicate variable names (for example, if the names have already been 
used in the calling function or procedure). In that case, the Debug 
Utility always gives precedence to the variable names used in the 
calling procedure. For further information on the Debug Utility, refer 
to chapter 9. 
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System-Dependent Procedures 

Of the procedures described here, some can be used only with 
NOS/VE; others may be available in variations of CYBIL on other 
operating systems, but they are not guaranteed to be. Keep in mind 
that programs using these procedures may not be transportable to 
other systems. 

To use these procedures properly and efficiently, you should be 
familiar with basic hardware concepts of your computer system. This 
information can be found in volume II of the virtual state hardware 
reference manual. 

The functions are described in alphabetical order. 

#CALLER_ID Procedure 

The #CALLER_ID procedure returns the identification (caller id) of 
the caller of a function or procedure. This procedure can be used only 
with NOS/VE. 

Use this format for the #CALLER_ID procedure call: 

#C ALLER _ ID(id .record); 

id _ record 

Name of the record that will contain the caller id information. 
It must be four bytes long. 

The caller id is a record that contains the key/lock fields, ring 
number, and segment number of the caller. (This information is found 
in the left half of the P register.) When a function or procedure is 
called, the caller id is placed in the leftmost 32 bits of the XO 
register as a result of a call relative (CALLREL) or call indirect 
(CALLSEG) hardware instruction. The #CALLER_ID procedure 
accesses XO while this information is there. 
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#CALLER ID 
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calling function or procedure to use this procedure. 

For further information on the caller id record and the CALLREL and 
CALLSEG instructions, refer to volume II of the virtual state 
hardware reference manual. 

Example: 

The following example sets the pointer variable PSA_PTR to point to 
the first cell of the previous save area. The #CALLER_ID procedure 
then returns information about the caller of the last function. That 
information is returned in the record CALLER_RECORD. In this 
example, CALLER_ RECORD is equivalent to the object of pointer 
PSA_PTR (that is, CALLER_RECORD = PSA_PTR*). 

TYPE 

id_rec = record 

id: . . 0ffffffff(16), 
recend; 



psa_ptr: "id_rec, 

cal 1er_record: id_rec; 

psa_ptr := #previous_save_area (); 
#ca11er_id (cal ler_record); 
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#COMPARE_SWAP 

#COMPARE_SWAP Procedure 

The #COMPARE_SWAP procedure performs actions equivalent to the 
compare swap (CMPXA) hardware instruction. It compares the 
contents of a variable with an expression. If the variable is unlocked 
and equal to the expression, the variable is swapped with a new 
expression. This procedure can be used only with NOS/VE. 

Use this format for the #COMPARE_SWAP procedure call: 

#COMPARE _ SWAP(lock .variable, initial .expression, 
new .expression, actual .variable, result .variable); 

lock .variable 

Name of the variable on which the compare swap operation is 
to be performed. This variable must be aligned on a word 
boundary. 

initial _ expression 

Expression that is compared to the lock variable. They must be 
equal for the swap operation to occur. 

new.expression 

Expression that specifies the value to be stored in the lock 
variable if the swap is successful (that is, the contents of lock_ 
variable equals initial.expression). The expression must be 
greater than zero and less than 2 32 -l. 

actual _ variable 

Name of the variable into which the initial contents of the lock 
variable is returned. If the lock variable is locked, this field is 
not changed. 
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#COMPARE_SWAP 

result_ variable 

Name of the variable into which the result of the compare 

swap instruction is returned, Specify a subrange from to 2 
where each value has the following significance: 



Swap operation was successful. 



Swap operation failed because the initial expression was not 
equal to the contents of the lock variable, 

2 

Swap operation failed because the lock variable was locked. 

The types of the lock variable, initial expression, new expression, and 
actual variable must be equivalent and have a size of eight bytes. 

The lock variable is said to be locked if the leftmost 32 bits are ones. 
If it is locked, no action occurs. If it is unlocked, the contents of the 
lock variable is assigned to the actual variable. Then the lock variable 
is compared to an initial expression. If they are equal, a new 
expression is assigned to the lock variable. Otherwise, no swap occurs. 

This procedure essentially performs the following statements: 

IF (left half of lock_ variable) = 0ffffffff(16) THEN 

result_ variable := 2; 
ELSE 

actual_ variable := lock_ variable; 
IF lock_variable = initial_expression THEN 
lock_variable := new_expression; 
result_ variable := 0; 
ELSE 

result_variable := 1; 
IFEND; 
IFEND; 
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#COMPARE_SWAP 

These statements are executed by the hardware as a noninterruptable 
sequence. Access to the lock_ variable from other sources, such as 
another processor or peripheral processor (PP), is prevented while 
these statements are being executed. 

For further information on the CMPXA instruction, refer to volume II 
of the virtual state hardware reference manual. 

Example: 

The following example compares the variable LOCK with INITIAL. If 
LOCK is unlocked and equal to INITIAL, the value of LOCK is 
replaced by the value of variable NEW. In this example, LOCK is 
unlocked and equal to INITIAL. Therefore, following completion of the 
procedure, LOCK is equal to NEW which is 10. The variable RESULT 
is indicating that the swap was successful. 



lock, 




initial , 




new, 




actual: integer, 




result: .. 2; 




lock := 5; 




initial := 5; 




new := 10; 




#compare_swap (lock, 


initial 



new, actual, result); 
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#CONVERT_POINTER_TO_PROCEDURE 
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The #CONVERT_POINTER_TO_PROCEDURE procedure converts a 
variable of the type pointer to procedure that has no parameters to a 
variable of the type pointer to procedure that can have parameters. 
This procedure may not be available on variations of CYBIL that 
execute on other operating systems. 

Use this format for the #CONVERT_POINTER_TO = PROCEDURE 
procedure call: 

#CON VERT.POINTER _ TO _ PROCEDURE(pointer _ 1, 
pointer _ 2); 

pointer _1 

Name of a pointer to procedure variable with no parameters. 

pointer _ 2 

Name of a pointer to procedure variable with an arbitrary 
parameter list. 

Example: 

The following example converts the variable PTR_TO_PROCl, a 
pointer to a procedure that has no parameters, to the variable PTR_ 
TO_PROC2, a pointer to a procedure that does have parameters. 

VAR 

ptr_to_procl: "procedure, 

ptr_to_proc2: "procedure (argl: integer, 

arg2: real); 

ptr_to_prod := "prod; 

#convert_pointer_to_procedure (ptr_to_proc1, ptr_to_proc2); 
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#HASH_SVA Procedure 

The #HASH_SVA procedure performs actions equivalent to the load 
page table index (LPAGE) hardware instruction. This instruction 
searches the system page table (SPT) for a given system virtual 
address (SVA). This procedure can be used only with NOS/VE. 

Use this format for the #HASH_SVA procedure call: 

#HASH_SVA(sva_ variable, index, count, result _ variable); 

sva_ variable 

Name of the variable that contains the SVA for which the 
instruction will search. 

index 

Name of an integer variable that will contain a word index 
into the SPT. If the SVA is found, this index points to the SPT 
entry for the SVA. If the SVA is not found, it points to the last 
entry searched. 

count 

Name of an integer variable that will contain the number of 
SPT entries searched. 

result _ variable 

Name of a boolean variable that is set to TRUE if the SVA is 
found. 

The procedure returns either an index within the table if the SVA is 
found, or an index of the last entry searched if the SVA is not found. 
It also returns the number of entries searched and a boolean value 
indicating whether the entry was found. 

For further information on the SVA, addressing, and the LPAGE 
instruction, refer to volume II of the virtual state hardware reference 
manual. 
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#KEYPOINT 
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The #KEYPOINT procedure generates an inline keypoint hardware 
instruction based on parameters supplied in the call. It allows 
performance monitoring of programs using keypoint instructions as 
trap interrupts. This procedure can be used only with NOS/VE. 

Use this format for the #KEYPOINT procedure call: 

#KEYPOINT(class, data, identifier); 

class 

A constant integer expession from to 15 that specifies the 
keypoint class. This value is placed in the j field of the 
hardware instruction. 

data 

A constant or variable expression from to OFFFFFFFF 
hexadecimal that specifies optional data to be collected with the 
keypoint. If you specify the constant 0, a is placed in the k 
field of the hardware instruction. If you don't specify 0, the 
value is placed in an X register and that register is placed in 
the k field of the hardware instruction. 

identifier 

A constant expression from to OFFFF hexadecimal that 
specifies a keypoint identifier. It is placed in the Q field of the 
hardware instruction. 

For further information on the KEYPOINT instruction, refer to 
volume II of the virtual state hardware reference manual. 
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#PURGE_BUPFER 

#PURGE .BUFFER Procedure 

The #PURGE_ BUFFER procedure performs actions equivalent to the 
purge hardware instruction. It purges the contents of cache or the 
map buffer. This procedure can be used only with NOS/VE. However, 
not all computer systems that support NOS/VE have cache and map 
buffers. If executed on a model without cache or map buffers, no 
action occurs. 

Use this format for the #PURGE_BUFFER procedure call: 

#PURGE _ BUFFER(option _ value, address); 

option _ value 

A constant integer expression from to 15 that specifies one of 
the following purge options: 



Purge all entries in cache that are included in the 512-byte 
block defined by the system virtual address (SVA) in Xj. 



Purge all entries in cache that are included in the active 
segment identifier (ASID) defined by the SVA in Xj. 

2 

Purge all entries in cache. 

3 

Purge all entries in cache that are included in the 512-b w te 
block defined by the process virtual address (PVA) in Xj. 

4-7 

Purge all entries in cache that are included in the segment 
number defined by the PVA in Xj. 

8 

Purge all entries in the map (page table map if entries are 
kept in separate maps) relating to the page table entry 
defined by the SVA in Xj. 
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#PURGE BUFFER 



Purge all entries in the map (page table map if entries are 
kept in separate maps) relating to the page table entries 
that are included in the segment defined by the SVA in Xj. 

10 or A(16) 

Purge all entries in the map (page table map if entries are 
kept in separate maps) relating to the page table entry 
defined by the PVA in Xj. 

11 or B(16) 

Purge all entries in the map (both the page table and 
segment map) relating to the segment table entry defined 
by the PVA in Xj, and to all page table entries included 
within that segment. 

12-15 or C(16)-F(16) 

Purge all entries in the map. 

address 

Name of a 6-byte variable that specifies the PVA or SVA of the 
data to be purged. 

For further information on addressing, cache and map buffers, and the 
purge instruction, refer to volume II of the virtual state hardware 
reference manual. 

Example: 

The following example purges all entries in cache that are in the 
block defined by the PVA in pointer variable PTR1. 

VAR 

i: integer, 
ptrl: "cell; 

Dtrl := "1 : 
#purge_buffer (3, ptrl); 
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#SCAN Procedure 

The #SCAN procedure scans a string from left to right until one of a 
specified set of characters is found or the entire string has been 
searched. This procedure may not be available on variations of CYBIL 
that execute on other operating systems. 

Use this format for the #SCAN procedure call: 

#SCAN (scan _ variable, string, index, result_ variable); 

scan _ variable 

Name of the variable that indicates the character values for 
which the string is scanned. The variable must be 256 bits 
long. Each bit of the variable represents the character in the 
corresponding position of the ASCII character set. If a bit is 
set, the corresponding character is one for which the procedure 
scans. 

string 

String or substring to be scanned. 

index 

Name of an integer variable. If a character is found during 
scanning, the index of that character is returned in this 
variable. The index of a character is that character's position 
in the string; for example, the index value of the first 
character is 1. If no matching values are found, the variable 
contains the string length plus one. 

result _ variable 

Name of a boolean variable that is set to TRUE if the scan 
finds one of the selected characters. 

The procedure looks for any one character from a set of characters 
specified in a 256-bit variable. Bits are set in the variable to 
correspond to the characters in the same positions in the ASCII 
character set collating sequence. A set bit indicates that the procedure 
scans the string for the corresponding character. The procedure stops 
if it finds one of the characters specified. It returns the position of the 
character that caused termination and the boolean variable that 
indicates whether a character was found. 
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#SCAN 

E! 1_. 

The following example searches the string variable SOURCE_STRING 
for the asterisk character (*). First, the character to be searched for 
(the asterisk) must be specified in the array variable SELECT. To do 
this, all 256 elements of SELECT are set to 0. Then the $INTEGER 
function is used to determine the position of the asterisk character in 
the ASCII character set collating sequence. The value returned in I is 
42 (because the asterisk is in the forty-second position in the collating 
sequence). The forty-second position in the array SELECT is then set 
to 1. Assuming SOURCE _ STRING contains an asterisk as the 
fifty-fourth character of the string, the value returned in INDEX is 54 
and the value returned in RESULT is TRUE. 

VAR 

source_string: string (100), 

select: packed array [0 .. 255] of .. 1, 

i , 

index: integer, 

result: boolean; 

FOR i := TO 255 DO 

select [i] := 0; 
FOREND; 

i := $INTEGER ('*'); 
select [i] := 1; 
#scan ( se 1 ect , sou r ce_st ring, i ndex , result); 
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#SPOIL Procedure 

The #SPOIL procedure causes the compiler to inhibit optimization of 
the specified variables the next time they are referenced and instead 
load their values from memory. Subsequent references to the variables 
are again subject to optimization. This procedure may not be available 
on variations of CYBIL that execute on other operating systems. 

Use this format for the #SPOIL procedure call: 

#SPOIL(name {, name}...); 

name 

Name of one or more variables for which optimization should 
be inhibited. You can specify a maximum of 127 variable 
names. 

When the CYBIL compiler generates optimized object code, variables 
may be moved or otherwise treated differently than if the code was 
not optimized. For example, local variables are stored in registers and 
carried there throughout execution rather than always being 
referenced from memory. Specifying a variable in the #SPOIL 
procedure call causes its value to be loaded from memory (rather than 
taken from a register) the first time it occurs in code after the 
#SPOIL procedure call. Following that reference, however, the 
compiler resumes optimizing of the variable. Inhibiting code 
optimization is sometimes necessary to control asynchronous uses of 
CYBIL variables. (For further information on optimization, refer to 
the description of the CYBIL command's OPTIMIZATION_LEVEL 
parameter in chapter 8.) 

The CYBIL compiler interprets this procedure as it would an external 
procedure and treats each actual parameter specified as if it were 
associated with a reference (VAR) formal parameter. However, the 
compiler does not generate any code when the procedure is referenced. 
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#SPOIL 

Example: 

The following example inhibits code optimizing for a variable, 
HEADER', to ensure that it contains an accurate status value before 
a channel is unlocked. HEADER* is a record variable that contains 
status and request codes. The WHILE statement loop checks the 
STATUS field of HEADER* , waiting for a change to occur on a disk 
which is being updated asynchronously. After the change on the disk 
occurs, a user-defined procedure UNLOCK_CHANNEL is called and 
the specified channel is unlocked. If the #SPOIL procedure was not 
included in the WHILE statement list and the code was optimized, the 
code that loads HEADER* .STATUS would be moved out of the WHILE 
loop and, because the disk is updated asynchronously, the value of the 
STATUS field would never change. 

IF header" .request _code IN disk_access_set THEN 

WHILE header" .status = dsc$dft_no_response DO 
#SPOIL (header"); 

WHILEND; 

unlock_channel (idle_channel ) ; 
IFEND; 
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#TRANSLATE Procedure 

The #TRANSLATE procedure translates each character in a source 
field according to a translation table, and transfers the result to a 
destination field. This procedure may not be available on variations of 
CYBIL that execute on other operating systems. 

Use this format for the #TRANSLATE procedure call: 

#TRANSLATE(table, source, destination); 

table 

Name of a string variable whose length is 256 characters. This 
variable defines the translation table. 

source 

String to be translated. 

destination 

Name of a string variable into which the translated string is 
transferred. 

Translation of the string occurs from left to right with each source 
byte used as an index into the translation table. Translated bytes 
from the table are stored in the destination field. 

If the length of the source field is less than the length of the 
destination field, translated spaces fill the destination field. If the 
source field is larger than the destination field, the rightmost 
characters of the source field are truncated. 

Example: 

The following example translates a string named SOURCE _ STRING 
according to an externally referenced translation table named 
TRANS1_TABLE. The resulting string is placed in DEST_STRING. 

VAR 

trans1_table: [XREF] string (256), 
source_string: string (100), 
dest_string: string (100); 

source_string (1, 10) := 'ten chars.'; 

translate (transl_table, sour ce_st ring, dest_string) ; 
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#UNCHECKED_CONVERSION 

#UNCHECKED .CONVERSION Procedure 

The #UNCHECKED_ CONVERSION procedure copies directly from a 
source field to a destination field. This procedure may not be available 
on variations of CYBIL that execute on other operating systems. 

Use this format for the #UNCHECKED_CONVERSION procedure 
call: 

#UNCHECKED _ CONVERSION(source, destination); 

source 

Name of a variable from which the copy is made. 

destination 

Name of a variable to which the copy is made. 

The source and destination fields must have the same length in bits. 
Neither the source nor the destination field can be a pointer or 
contain a pointer. If either the source or destination field is the object 
of a pointer reference (pointer"'), the pointer cannot be a pointer to a 
procedure. 
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#UNCHECKED_CONVERSION 

The destination field must satisfy the same restrictions as the target 
of an assignment statement. This means that the destination field 
cannot be: 

• A read-only variable 

• A formal value parameter of the procedure that calls the 
#UNCHECKED_CONVERSION procedure 

• A bound variant record 

• The tag field name of a bound variant record 

• A heap 

• An array or record that contains a heap 

Example: 

The following example copies the contents of a 5-character string 
named SOURCE to a 5-element array named DESTINATION. After 
the operation, the contents of both variables are identical. 

VAR 

source: string (5), 

destination: packed array [1 .. 5] of char; 

#unchecked_conversion (source, destination); 
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#WRITE_REGISTER 

# WRITE _ REGISTER Procedure 

The #WRITE_REGISTER procedure performs actions equivalent to 
the copy to state register (CPYXS) hardware instruction. It allows a 
program to change the contents of a process or processor register. 
This procedure can be used only with NOS/VE. 

Use this format for the #WRITE_ REGISTER procedure call: 

#WRITE _REGISTER(register _id, data); 

register., id 

An integer expression from to 255 that identifies the number 
of the register to be written. Register numbers are given in 
volume II of the virtual state hardware reference manual. 

data 

Integer expression that contains the data to be written to the 
register. 

The #READ_REGISTER function described in chapter 6 allows a 
program to read the contents of a process or processor register. 

Writing to certain registers requires special privileges. For further 
information on process and processor registers, and the CPYXS 
instruction, refer to volume II of the virtual state hardware reference 
manual. 

Example: 

The following example changes the contents of register E5, the Debug 
mask register, to IF hexadecimal. 

VAR 

i: Integer; 

i := 01f(16); 
#write_register (0e5(16), i): 
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Compiling and Formatting Source Code 8 

This chapter describes how to compile and format CYBIL source code. 

Compiling Source Code 8-1 

CYBIL Command 8-2 

Compilation Declarations and Statements 8-8 

Compile-Time Variables 8-8 

Compile-Time Expressions 8-9 

Compile-Time Assignment Statement 8-9 

Compile-Time IF Statement 8-10 

Compile-Time Directives 8-12 

COMMENT Directive 8-14 

COMPILE Directive 8-14 

EJECT Directive 8-15 

LEFT Directive 8-15 

LIBRARY Directive 8-16 
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Compiling and Formatting Source Code 8 

This chapter describes how to compile and format CYBIL source code. 
You compile source code using the CYBIL command and compile-time 
declarations, statements, and directives that you insert at the 
appropriate place in the code. You format source code using the 
FORMAT_CYBIL_SOURCE command and formatting directives 
likewise inserted in the code. (These directives in the code are called 
text-embedded directives.) 

The CYBIL command and the FORMAT__CYBIL_SOURCE command 
are standard system commands. They use the same syntax and 
language elements for parameters that are described in the SCL 
Language Definition manual. 

Compiling Source Code 

The CYBIL command compiles one or more modules of CYBIL source 
code. Compilation statements and directives are used to construct the 
unit to be compiled and to control that T >rocess. If the CYBIL 
command and a directive specify conflicting options, the directive 
encountered most recently is used. The CYBIL command, statements, 
and directives are described later in this section. 

The maximum number of lines allowed in a single compilation unit is 
65,535 if no run-time checking is performed. If run-time checking is 
selected, the maximum number of lines allowed is 32,767. In one 
compilation unit, there can be up to 16,383 unique names and up to 
99S user-defined procedures. At most, 2,000 error messages can be 
generated for any one module within a compilation unit. 

For further information on program execution, refer to the SCL Object 
Code Management manual. 
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CYBIL Command 

Purpose Calls the compiler, specifies the files to be used for input 

and output, and indicates the type of output to be 
produced. 

Format CYBIL 

INPUT = file 

LIST=file 

BINARY=fde 

LIST_OPTIONS=list of keyword 

DEBUG _AIDS=list of keyword 

ERROR _LEVEL = keyword 

OPTIMIZATION _LEVEL = keyword 

PAD = integer 

RUNTIME _CHECKS= list of keyword 

STATUS = status variable 

Parameters INPUT or I 

The file that contains the source text to be read. You can 
specify a file position as part of the file name. Source 
input ends when an end-of-partition or an 
end-of-information is encountered on the source input file. 
If it is omitted, $INPUT is assumed. 

LIST or L 

The file on which the compilation listing is to be written. 
You can specify a file position as part of the file name. If 
you specify $NULL, all compile-time output is discarded. 
If it is omitted $LIST is assumed. 

BINARY or B or BINARY_OBJECT or BO 

The file on which object code is to be written. You can 
specify a file position as part of the file name. If you 
specify $NULL, the compiler performs a syntactic and 
semantic scan of the program but does not generate object 
code. If it is omitted, $LOCAL.LGO is assumed. 
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A combination of the following list options. If you specify 
NONE, no list options are selected. If it is omitted, option 
S (list the source input file) is assumed. 

A 

Produces an attribute list of source input block 
structure and relative stack. The attribute listing is 
produced following the source listing on the file 
specified by the LIST parameter or, if you omit the 
LIST parameter, on file $LIST. 



Produces a full listing. In effect, this option selects 
options A, S, and R. 



Lists compiler-generated object code. When selected, 
this listing includes an assembly-like listing of the 
generated object code. This option has no effect if the 
BINARY_ OBJECT parameter is set to $NULL. 

R 

Produces a symbolic cross-reference listing showing the 
location of a program entity definition and its use 
within a program. 

RA 

Produces a symbolic cross-reference listing of all 
program entities whether referenced or not. 

S 

Lists the source input file. 



Used in conjunction with the compile-time directive 
LISTEXT so that listings can be externally controlled 
using the CYBIL command. The LISTEXT toggle must 
be ON. For further information, refer to the SET, 
PUSH, POP, and RESET directives later in this 
chapter. 
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DEBUG _ AIDS or DA 

A combination of the following debug options. If it is 
omitted, NONE (no debug options) is assumed. 

ALL 

Selects debug options DS and DT. 

DS 

Compiles all debugging statements. A debugging 
statement is a statement in the source text that is 
ignored unless this option is specified. These 
statements are enclosed by the compile-time directives 
COMPILE and NOCOMPILE (described later in this 
chapter). 

DT 

Generates debug tables (that is, the symbol table and 
line table) as part of the object code. These tables are 
used by the Debug Utility. 

NONE 

No debug options are selected. 

ERROR_LEVEL or EL 

One of the following error list options. If it is omitted, W 
(list warning and fatal diagnostics) is assumed. 

F 

Lists fatal diagnostics. If it is selected, only fatal 
diagnostics are listed. 

W 

Lists warning (informative) diagnostics as well as fatal 
diagnostics. 
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CYBIL Command 

OTIMIZATION _LEVEL or OL or OPTIMIZATION or 
OPT 

One of the following optimization options. If it is omitted, 
LOW is assumed. 

DEBUG 

Object code is stylized to facilitate debugging. Stylized 
code contains a separate packet of instructions for each 
executable source statement; it carries no variable 
values across statement boundaries in registers, and it 
notifies Debug each time the beginning of a statement 
or procedure is reached. 

LOW 

Provides for keeping constant values in registers. 

HIGH 

Provides for keeping local variables in registers, 
passing parameters to local procedures in registers, 
and eliminating redundant memory references, common 
subexpressions, and jumps to jumps. When this option 
is selected, the RUNTIME_CHECKS parameter cannot 
be specified. 

PAD 

The number of no-op (no operation) instructions generated 
between instructions that perform operations. If it is 
omitted, zero is assumed; no-op instructions are not 
generated. 
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RUNTIME _CHECKS or RC 

A combination of the following run-time checking options. 
This parameter cannot be specified when 
OPTIMIZATION. LEVEL = HIGH is also specified. If it is 
omitted, NONE (no run-time checks) is assumed. 

ALL 

Selects run-time checking options N, R, and S. 

N 

Produces compiler-generated code that checks for a 
NIL value when a reference is made to the object of a 
pointer. 

NONE 

No run-time checks are produced. 

R 

Produces compiler-generated code to check ranges. 
Range checking code is generated for assignment to 
integer subranges, ordinal subranges, and character 
variables. All CASE statements are checked to ensure 
that the selection expression corresponds to one of the 
variant values specified if no ELSE clause is provided. 
All references to substrings are verified. If you specify 
an offset (variable pointer) on a RESET statement, it 
is checked to ensure that it is valid for the specified 
sequence. 

S 

Produces compiler-generated code to test the 
subscripting of arrays. 



8-6 CYBIL Language Definition Revision F 

W | 01/22/87 19:59:24 | 02/13/87 09:46:31 I 87/03/25 22.17.32 I 60464113 F I SOURCE CODE I DRAFT COPY 



CYBIL Command 



Remarks 



Examples 



An optional SCL status variable in which the completion 
status of the command is returned. If it is specified, the 
compiler returns a status to this variable indicating 
whether any fatal errors were found during the 
compilation that was just completed. You can test this 
status variable and take special action if fatal compilation 
errors occurred. If it is omitted and the status returned 
from the compiler is abnormal, SCL terminates the 
current command sequence. 

If the compiler command specifies an option that differs 
from a directive, the latest occurrence of either the 
command or the directive takes precedence. 

This command reads source code from a file named 
COMPILE, writes the compilation listing on file LIST, and 
writes the object code on file BIN1. The listing includes 
source code, compiler-generated object code, and a 
symbolic cross-reference listing. 

cybil i=compile 1=1 ist b=biM lo=(o,r) 
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Compilation Declarations and Statements 

Many program elements defined in CYBIL have counterparts that can 
be used to control the compilation process. They include variable 
declarations, expressions, and the assignment and IF statements. The 
IF statement is used to specify certain areas of code to be compiled. 
The IF statement requires the use of expressions, which in turn 
require variables. Assignment statements are used to change the value 
of variables and, thus, expressions. 

Compile-Time Variables 

Only boolean type variables can be declared. 

Use this format to specify a boolean type compile-time variable: 

? VAR name {,name}... : BOOLEAN := expression 

/, name {,name}... : BOOLEAN := expression}... ?; 

name 

Name of the compile-time variable. This name must be unique 
among all other names in the program. 

expression 

A compile-time expression that specifies the initial value of the 
variable. 

A compile-time declaration must appear before any compile-time 
variables are used. The scope of such a variable extends from the 
point at which it is declared to the end of the module. Compile-time 
variables can be used only in compile-time expressions and 
compile-time assignment statements. The maximum number of 
compile-time variables that can be used in a compilation unit is 1,023. 
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Compile-time expressions are composed of operands and operators like 
CYBIL-defined expressions. An operand can be: 

• Either of the constants TRUE or FALSE 

• A compile-time variable 

• Another compile-time expression 

The operators are NOT, AND, OR, and XOR. Their order of 
evaluation from highest to lowest is: 

• NOT 

• AND 

• OR and XOR 

These operators have their usual meanings, as described under 
Operators in chapter 5. 

Compile-Time Assignment Statement 

A compile-time assignment statement assigns a value to a 
compile-time variable. 

Use this format for the compile-time assignment statement: 

? name := expression ?; 

name 

Name of a compile-time variable. 

expression 

A compile-time expression. 
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Compile-Time IF Statement 

The compile-time IF statement compiles or skips a certain area of 
code depending on whether a given expression is true or false. 

Use this format for the compile-time IF statement: 

? IF expression THEN 
code 

{ ? ELSE 
code } 
? IFEND 

expression 

A boolean compile-time expression. 

code 

An area of CYBIL code or text. 

When the expression is evaluated as true, the code following the 
reserved word THEN is compiled. When compilation of that code is 
completed, compilation continues with the first statement following 
IFEND. When the expression is false, compilation continues following 
the ELSE phrase, if it is included, or following IFEND. 

The ELSE clause is optional. If it is included, the ELSE clause 
designates an area of code that is compiled when the preceding 
expression is false. 
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The following example shows the declaration of a compile-time 
variable named SMALL _ SIZE that is initialized to the value TRUE. 
A line of CYBIL code declaring an array named TABLE is compiled. 
Then a compile-time IF statement checks the value of SMALL_SIZE. 
If it is TRUE, the line of CYBIL code that calls a procedure named 
BUBBLESORT is compiled in the program. If it is FALSE, the code 
that calls procedure QUICKSORT is compiled instead. Because 
SMALL_SIZE was initialized to TRUE, the call to BUBBLESORT is 
included in the compiled program. 

?VAR 

small_size: boolean := TRUE?; 

VAR 

table: array [1 .. 50] of integer; 

?IF smal l_size = TRUE THEN 

bubblesort (table); 
?ELSE 

quicksort (table); 
? 

I FEND 
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Compile-Time Directives 

Compile-time directives allow you to perform many activities during 
compilation. They can be grouped into five major categories: 

• Toggle control (the SET, PUSH, POP, and RESET directives) 

• Layout control (the LEFT, RIGHT, EJECT, SPACING, SKIP, 
NEWTITLE, TITLE, and OLDTITLE directives) 

• Maintenance control (the COMPILE and NOCOMPILE directives) 

• Object code comment control (the COMMENT directive) 

• Object library control (the LIBRARY directive) 

You can turn on or off various listing options and run-time options 
using the SET and PUSH directives. The SET directive specifies new 
settings that replace the current settings. The PUSH directive, on the 
other hand, causes the current settings to be saved before initiating 
the new settings. In that case, the POP directive can be used to 
restore the last settings that were saved by the PUSH directive. The 
RESET directive restores the original settings and discards any 
settings that were saved. 

The LEFT and RIGHT directives specify the margins of the source 
text to be read. Any text to the left of the left margin or the right of 
the right margin is ignored. The remaining layout control directives 
format the listing that results from compilation. The EJECT directive 
advances the paper to the top of the next page. The SPACING 
directive specifies single, double, or triple spacing between lines of the 
listing. The SKIP directive skips a specified number of lines. The 
TITLE, NEWTITLE, and OLDTITLE directives indicate titles that are 
printed on every page of the listing. 
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which should or should not be compiled. 

The COMMENT directive inserts a comment in the object module that 
is generated during compilation. 

The LIBRARY directive associates one or more object libraries with 
the object module so that the loader can satisfy external references 
from those libraries. 

You can specify one or more directives with the format: 

?? directive {,directive}... ?? 

directive 

One of the directives discussed in the remainder of this 
chapter. 

Directives must be bounded by a pair of consecutive question marks. 
These delimiters are not shown in the following formats for individual 
directives, but they are required around one or more directives. 

If a directive conflicts with an option specified on the CYBIL 
command, the most recent directive takes precedence. 
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COMMENT Directive 

The COMMENT directive causes the compiler to include the given 
character string in the commentary portion of the object module 
generated by the compilation process. 

Use this format for the COMMENT directive: 

COMMENT := 'character .string' 

character _ string 

A character string of up to 40 characters that specifies a 
compile-time comment. 

This directive allows you to include comments in object modules so 
that the comments appear in the load maps. Any number of comments 
can be included, but only the last comment encountered appears. 

Example: 

?? COMMENT := 'Copyright 1985 by Control Data Corporation' ?? 

COMPILE Directive 

The COMPILE directive causes compilation to occur, or to resume 
after the occurrence of a NOCOMPILE directive. 

Use this format for the COMPILE directive: 

COMPILE 

If you don't, use either the COMPILE or NOCOMPILE directive, the 
COMPILE directive is assumed; source code is compiled. 

When the CYBIL command includes the DEBUG_AIDS parameter 
with DS specified, debugging statements enclosed by the NOCOMPILE 
and COMPILE directives are compiled. 
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The EJECT directive causes the paper to be advanced to the top of 
the next page. 

Use this format for the EJECT directive: 

EJECT 

LEFT Directive 

The LEFT directive specifies the column number of the left margin of 
the source text. 

Use this format for the LEFT directive: 

LEFT := integer 

integer 

An integer value that represents the column number of the left 
margin. The left margin must be greater than zero. 

All source text left of the left margin is ignored. If you don't use the 
LEFT directive, the left margin is assumed to begin in column 1. 

The LEFT directive can also be used as a formatting directive. If it is 
encountered after a FORMAT_CYBIL_SOURCE command is issued, 
the formatter starts all of its formatted output at the left margin 
specified on the LEFT directive. 

The RIGHT directive, described later in this section, specifies the 
column number of the right margin. 

Example: 

This example sets the left margin at column 1 and the right margin 
at column 110. 

?? LEFT := 1, RIGHT r= 110 ?? 
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LIBRARY Directive 

The LIBRARY directive allows you to specify an object library from 
which external references in the compilation unit can be satisfied. 

Use this format for the LIBRARY directive: 

LIBRARY := library _ name 

library _ name 

A string constant that specifies the name of the library. This 
string must be a valid NOS/VE file name (although the 
compiler does not check for its validity). In addition, the string 
cannot contain the CAT (concatenation) operation or the 
$CHAR function. 

As a result of this directive, the compiler includes the specified 
library name in the library record of the object module that is 
produced during compilation. 1 This allows externally referenced 
declarations to be linked with the appropriate object library. Even if 
the same library name is found in more than one directive, the 
library is entered in the library record of the object module only once. 

Example: 

This example will cause the loader to search the object library MY_ 
CYB_ LIBRARY to satisfy external references in the compilation unit. 

?? LIBRARY := 'MY_CYB_LIBRARY' ?? 



1. For further information about the library record and the format of the object module, 
refer to the SCL Object Code Management manual. 
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The NEWTITLE directive specifies a new, additional title to be used 
on a page while saving the current title. 

Use this format for the NEWTITLE directive: 

NEWTITLE := 'character .string' 

character _ string 

A character string specifying the title to be used. A single 
quote mark is indicated by two consecutive quote marks 
enclosed by quote marks [that is, ""]. 

The current title is saved and the given character string becomes the 
current title. A standard page header is always the first title printed 
on a page, followed by user-defined titles in the order in which they 
were saved. This means that titles are saved and restored in a last 
in-first out order, but they are printed in a first in-first out order. 
There is always a single empty line between the standard page header 
and any user-defined titles. There is always at least one empty line 
between the last title and the text. 

The maximum number of titles that can be specified is 10. Any 
attempts to add more titles is ignored. 

Titling does not take effect until the top of the next printed page. 
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NOCOMPILE Directive 

The NOCOMPILE directive causes compilation to stop until the 
occurrence of a COMPILE directive or the end of the module. 

Use this format for the NOCOMPILE directive: 

NOCOMPILE 

NOCOMPILE continues listing source code and text according to the 
listing toggles and layout directives, interpreting and obeying 
directives, but source code is not compiled until a COMPILE directive 
is encountered or a MODEND statement is encountered. 

When the CYBIL command includes the DEBUG_AIDS parameter 
with DS specified, debugging statements enclosed by the NOCOMPILE 
and COMPILE directives are compiled. 

OLDTITLE Directive 

The OLDTITLE directive restores the last user-defined title that was 
saved, making it the current title. 

Use this format for the OLDTITLE directive: 

OLDTITLE 

If there is no saved title, no action occurs. 
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The POP directive restores the last toggle settings that were saved by 
the PUSH directive. 

Use this format for the POP directive: 

POP 

If no record was kept (such as when a SET directive is performed), 
the initial settings are restored. 

Example: 

This example shows a PUSH directive that temporarily turns off 
listing. The POP directive restores listing. 

?? PUSH (LIST := OFF) ?? 
?? POP ?? 
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PUSH Directive 

The PUSH directive specifies the setting of one or more toggles like 
the SET directive, but before the settings are put into effect, a record 
of the current state of all toggles is saved for later use. 

Use this format for the PUSH directive: 

PUSH (toggle .name := condition {,toggle_name := condition}..) 

toggle _name 

Name of the toggle being set. Listing toggles are described in 
table 8-1. Run-time checking toggles are described in table 8-2. 
The names of toggles can be used freely outside of directives. 

condition 

ON or OFF. If a toggle is ON, the activity associated with it is 
performed during compilation; if it is OFF, the activity is not 
performed. 

Settings in the PUSH list are performed in the same manner as a 
SET list. If the directive list contains more than one setting for a 
single toggle, the rightmost setting in the list is used. 

The POP directive, described earlier in this chapter, restores the 
original toggle settings in a last in-first out manner (that is, the last 
record to be saved is the first to be restored). A maximum of 25 
toggle control directives can be stacked in a compilation unit. 

Example: 

This example turns off listing temporarily, that is, until the POP 
directive is encountered. 

?? PUSH (list •= OFF) ?? 
?? POP ?? 



8-20 CYBIL Language Definition Revision F 

W I 01/22/87 19:59:24 | 02/13/87 09:46:31 | 87/03/25 22.17.32 | 60464113 F I SOURCE CODE I DRAFT COPY 



Compile-Time Directives 



xauie o-l cteseriDes tne listing toggles tuiu gives tiieii initial settings. 



Table 8-1. Listing Toggles 



Toggle 



Initial 
Value 



Description 



LIST 



ON 



LISTOBJ 



LISTCTS 



OFF 



OFF 



Determines whether other listing toggles 
are read. When ON, a source listing is 
produced and the other listing toggles are 
used to control other aspects of listing. 
When OFF, no listing is produced; the 
other listing toggles are ignored. 

Controls the listing of generated object 
code. When ON object code is inters r >ersed 
with source code following the 
corresponding source code line. 

Controls the iisting of the listing toggle 
directives and layout directives. 



LISTEXT OFF When ON, the listing of source statements 

is controlled by a parameter (LIST_ 
OPTIONS =X) on the CYBIL compiler 
command. 

LISTALL Not This option represents all of the listing 

applicable toggles. When ON, all other listing toggles 
are ON; when OFF, all other listing 
toggles are OFF. 
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Table 8-2 describes the run-time checking toggles and gives their 
initial settings. These initial settings apply only if the corresponding 
options were selected on the RUNTIME_CHECKS parameter of the 
CYBIL command. 

Table 8-2. Run-Time Checking Toggles 



Toggle 



CHKNIL 



CHKALL 



Initial 
Value 



Description 



CHKRNG ON 



CHKSUB ON 



OFF 



Not 
applicable 



Controls the generation of object code that 
performs range checking of scalar subrange 
assignments and CASE statement 
variables. 

Controls the generation of object code that 
checks array subscripts (indexes) and 
substring selections to verify that they are 
valid. 

Controls the generation of object code that 
checks for a NIL value when a reference is 
made to the object of a pointer. 

This option represents all run-time 
checking toggles. When ON, all other 
run-time checking toggles are ON; when 
OFF, all other run-time checking toggles 
are OFF. 



RESET Directive 

The RESET directive restores the initial toggle settings. 

uoc taixo iui mat lui fclic xvuDux Uiictlivc. 

RESET 

When the RESET directive is performed, any record of previous 
settings is destroyed. 
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The RIGHT directive specifies the column number of the right margin 
of the source text. 

Use this format for the RIGHT directive: 

RIGHT := integer 

integer 

An integer value that represents the column number of the 
right margin. The right margin must be greater than or equal 
to the left margin plus 10, and less than or equal to 110; that 
is: 

left margin + 10 ^ right margin ^ 110 

All source text right of the right margin is ignored. If nonblank 
characters appear in the source text after the right margin, the 
compiler places a vertical line in the source listing immediately 
following the right margin. This indicates that the compiler stopped 

S^miiiiiig i,ilG iiXiC ttt hLiiS.ii pUiilL. 

If you don't use the RIGHT directive, the right margin is assumed to 
be column 79. 

The RIGHT directive can also be used as a formatting directive. If it 
is encountered after a FORMAT. CYBIL_ SOURCE command is issued, 
the formatter ends its formatted output at the right margin specified 
on the RIGHT directive. 

The LEFT directive, described earlier in this section, specifies the 
column number of the left margin. 

Example: 

This example sets the left margin at column 1 and the right margin 
at column 110. 

?? LEFT := 1, RIGHT := 110 ?? 
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SET Directive 

The SET directive specifies the setting of one or more toggles. 
Use this format for the SET directive: 

SET (toggle. name := condition {,toggle_name := condition}..) 

toggle _name 

Name of the toggle being set. Listing toggles are described in 
table 8-1. Run- time checking toggles are described in table 8-2. 
The names of toggles can be used freely outside of directives. 

condition 

ON or OFF. If a toggle is ON, the activity associated with it is 
performed during compilation; if it is OFF, the activity is not 
performed. 

All settings specified in the SET directive are done at the same time. 
If the directive list contains more than one setting for a single toggle, 
the rightmost setting in the list is used. 

SKIP Directive 

The SKIP directive specifies that a given number of lines is to be 
skipped. 

Use this format for the SKIP directive: 

SKIP := lines 

lines 

Integer value specifying the number of lines to skip. Specify a 
value greater than or equal to 1. 

If you specify more lines than the number of lines on the page, or if 
you specify a value for lines that would cause the paper to skip past 
the bottom of the current page, the paper is advanced to the top of 
the next page. 
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Compile-Time Directives 



The SPACING directive specifies the number of blank lines between 
individual lines of the listing. 

Use this format for the SPACING directive: 

SPACING := spacing 

spacing 

One of the values 1, 2, or 3 specifying single, double, and 
triple spacing, respectively. 

An undefined value has no effect on spacing, but an error message is 
issued. 

If you don't use the SPACING directive, single spacing (no intervening 
blank lines) is assumed. 

TITLE Directive 

mi__ rmmr ri Ji x: ._i it__ i. ~_ j-« 3 j.:^i~ — ul i-U- 

xlle xi±uCj uiiecuve icpitujes we cwreui usei -ueiiiieu tn/ie wiiJi wie 

given character string. 
Use this format for the TITLE directive: 
TITLE := 'character_string' 

character _ string 

A character string specifying the title to be used. A single 
quote mark is indicated by two consecutive quote marks 
enclosed by quote marks [that is, ""]. 

If there is no user-defined title currently, the character string becomes 
the current title. 

A standard page header is always the first title printed on a page. 
There is always a single empty line between the standard page header 
and any user-defined titles. There is always at least one empty line 
between the last title and the text. 

Titling does not take effect until the top of the next printed page. 
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Formatting Source Code 

Formatting Source Code 

Formatting CYBIL source code is useful because it improves the code's 
consistency, readability, and maintainability. The CYBIL source code 
formatter arranges source code using its own rules and, optionally, 
rules that you set for it. You can specify these optional formatting 
rules either as parameters on the FORMAT_CYBIL_ SOURCE 
command or as directives embedded in the code itself. 

With the FORMAT_CYBIL_SOURCE command, you can choose: 

• Whether comments are set off by blank lines 

• Whether the statements EXIT, CYCLE, and RETURN are specially 
marked to indicate a change in the flow of the program 

• Whether successive spaces are compressed or left as is 

• The line width of the formatted output line 

• The key character that indicates Source Code Utility directives 
which should not be formatted 

With the text-embedded directives FMT, LEFT, and RIGHT, you can 
choose: 

• Whether or not the lines that follow the directive should be 
formatted or left as is 

• Whether successive spaces are compressed or left as is 

• Tab settings for specific characters 

• The number of spaces to indent when indentation is called for 

.l^li, *w.v wiiu LLgjiiv xxxo.1 gXAia ui *jXAC XUlUiabWU UUbpUL \111 C-UCUL., Lilt! 

initial left margin and the line width) 



8-26 CYBIL Language Definition Revision F 

W | 01/22/87 19:59:24 | 02/13/87 09:46:31 | 87/03/25 22.17.32 | 60464113 F | SOURCE CODE | DRAFT COPY 



Formatting Source Code 



ijie Option to compress space cuaracters anu trie line wiutn oi tiie 
output line can be specified on both the command and the directives. 
If conflicting options are found, the most recent directive always takes 
precedence over the command. 

Formatting directives are processed only after the FORMAT_CYBIL_ 
SOURCE command is issued; otherwise, they are ignored. (The LEFT 
and RIGHT directives, however, can also be used as compilation 
directives. Refer to the individual descriptions of these directives for 
further information.) The command and directives are described later 
in this section. 

The source code to be formatted does not have to be a complete 
compilation unit, but it should be syntactically correct. Each line can 
be a maximum of 256 characters. Multiple partitions on the source 
file are formatted. 

Error messages are written to an error file. You can specify this file 
with the ERROR parameter on the FORMAT_CYBIL_ SOURCE 
command. If you omit it, errors are written on the local file 
$ERRORS. An error does not cause formatting to stop; the entire 
source file is always processed. 
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Formatting Source Code 

Example: 

The following example shows CYBIL source code as a user may have 
entered it and how it would look after formatting. 

/copy_fi le $user .unformatted_program 

procedure exit_example; 

var i: integer, key:string(7), 

names: [read] array [1..4] of string(7) :=t'jqp8402', 'jxd1432', 

'efd3204','led4411'] ; 

key:='efd3204' ; 

/find_key/ 

for i :=lowerbound(names) to upperbound(names) do 

if key=names[i] then exit /find_key/; 

i fend ; 

f orend/f i nd_key/ ; 

procend exit_example; 

/format _cybi 1 .source i=$user.unformatted_program .. 

. . /o=$user . format ted_program 

/copy_f i le $user . format ted_program 

PROCEDURE exit_example; 

VAR 

i: integer, 

key: string (7), 

names: [READ] array [1 ..4] of string (7) := 

[' jqp8402' , ' jxd1432' , 'efd3204' , ' led44l 1 ' ] ; 



/find_key/ 

FOR i := LOWERBOUND (names) TO UPPERBOUND (names) DO 
IF key = names [i] THEN 

EXIT /find. key/; 
I FEND; 
FOREND/find_key/; 
PROCEND exit_example; 
/ 
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FORMAT_CYBIL_SOURCE 

FuRiviAi_uii5ii J _»ULiiiuiii uommana 

Purpose Formats CYBIL source code for consistency and greater 

readability. 

Format FORMAT. CYBIL SOURCE or 

FORCS 

INPUT = file 

OUTPUT=file 

ERROR = file 

FORMAT_OPTIONS=list of keyword 

LINE_ WIDTH =integer 

KEY = character 

STATUS = status variable 

Parameters INPUT or I 

The file from which the CYBIL source code is read. The 
file path specified for the input file cannot be the same as 
the file path specified for the output file. If you don't 
specify a file position in the file reference, this file is 
rewound before formatting. If it is omitted, SINPUT is 
assumed. 

OUTPUT or 

The file on which the formatted CYBIL source code is 
written. The file path specified for the output file cannot 
be the same as the file path specified for the input file. If 
you don't specify a file position in the file reference, this 
file is rewound before being written. If it is omitted, 
$OUTPUT is assumed. 

ERROR or E 

The file on which error messages are written. If it is 
omitted, $ERRORS is assumed. 
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FORMAT CYBIL SOURCE 



FORMAT_OPTIONS or FO 

One or more of the following format options. If it is 
omitted, NONE (no format options are selected) is 
assumed. 



ALL 



COMMENT. 
BLOCK or 
CB 



MARK_ 
EXIT or ME 



Selects all the format options (CB, ME, 
and NC). 

Specifies that a comment block is preceded 
and followed by a blank line. A comment 
block is considered to be one or more lines 
of comments. If a blank line already 
exists, none is added. Also, no blank lines 
are inserted within a comment block. 

Marks exit statements (that is, EXIT, 
CYCLE, and RETURN) by adding the 
comment 



NO_ 

COMPRESS 
or NC 



NONE 



{ > 

after the statement. This indicates that a 
change in the program's flow of control 
occurs here. 

If the comment delimiter (the left brace) 
is already in the statement, the statement 
is not changed. 

Selects no compression of successive space 
characters. The same number of space 
characters in the input file are written to 
the output file. This option is overridden if 
the formatter finds an FMT directive in 
the source code with the COMPRESS 

pctl Clint; liCl OCU i/U \J±*% . 

specified, spaces are compressed. 
No format options are selected. 
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FORMAT CYBIL SOURCE 



T ThTTT TJ7TT\rrm -_ T-ITT 
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The line width of the formatted output. You can specify 
an integer from 11 to 110. Specifying a line width sets 
the left margin to column 1 and the right margin to the 
value of the line width. If it is omitted, a right margin of 
78 is assumed. 

This setting is overridden if the formatter finds the LEFT 
and RIGHT layout control directives in the source code. 

KEY ax K 

The key character that indicates embedded Source Code 
Utility directives. Statements that begin with the key 
character in column 1 are not formatted. If it is omitted, 
the asterisk character is assumed. 

STATUS 

An optional SCL status variable in which the completion 
status of the command is returned. 

Remarks The file paths specified for the input and output files 
cannot be the same. For example, INPUT =PROCl and 
OUTPUT = PROCl are not valid; INPUT =$LOCAL.PROCl 
and OUTPUT =$USER.PROCl, however, are valid. 

Examples This command formats the CYBIL source program 
contained on file INITIAL and writes it to file 
$USER.FINAL. 

format^cybi l_source initial $user. final 
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Formatting Directives 

Formatting Directives 

You can insert directives in the source code itself that direct how 
formatting is done. These directives are the formatting directive FMT 
and the layout control directives LEFT and RIGHT. The FMT 
directive determines what formatting is done. The layout control 
directives set the margins for the formatted output. 

You can specify one or more directives with the following format: 

?? directive {, directive}... ?? 

directive 

One of the formatting directives FMT, LEFT, or RIGHT as 
described in the remainder of this section. 

If an option specified on a directive differs from one selected on the 
FORMAT_CYBIL_ SOURCE command, the most recent directive takes 
precedence. 
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FMT 



■chit T»;-~„iC..^ 

The FMT directive controls formatting options such as when to format 
lines, whether multiple spaces are compressed, where tabs should be 
set for certain characters, and how to indent block-type statements. 
The options specified on the directive take effect starting with the 
next source code statement that is processed. They remain in effect 
until the entire file is formatted or another directive is encountered. 

Use this format for the FMT directive: 

FMT (FORMAT := keyword, 
COMPRESS : = keyword, 
TAB := 'tab^character', integer {, integer}..., 
CLEARTAB := 'tab ^character', integer {, integer}..., 
uhuemSS'i := integer) 

FORMAT 

Specifies whether formatting is to take place. ON indicates that 
all source code lines, beginning with the line following this 
directive, are formatted. OFF indicates that all lines, beginning 
with the line following this directive, are not formatted. If it is 
omitted, ON (lines are formatted) is assumed. 

COMPRESS 

Specifies whether successive space characters are compressed to 
a single space. ON indicates that multiple space characters 
appearing together in the original code are compressed to one 
space character in the formatted code. OFF indicates that 
successive space characters are transferred to the formatted file 
unchanged. If it is omitted, ON (successive spaces are 
compressed) is assumed. 
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FMT 



TAB 

Tab settings that are used for the indicated characters. Use the 
following format to specify this parameter: 

'tab_charaeter', integer {, integer }... 

The tab_character is from 1 to 8 characters. When the 
formatter recognizes that character or set of characters, it 
moves to the next available tab column as specified by the 
integers. For example, if the following TAB parameter was 
specified 

?? fmt (tab:= '{', 5, 20) ?? 

and the formatter encountered a left brace in the first four 
columns of the source code, it would move the brace and the 
text following it to start at the fifth column. If the brace was 
found past the fifth column of the source code, it and the 
following text would be moved to start at the next tab position, 
column 20. If the specified character or characters are found 
past the last tab position that was specified, no text is moved; 
the characters stay in the same position. 

The tab_character must be a valid CYBIL symbol (for 
example, {or : = ). If a tab_character is specified, at least one 
integer setting must also be specified; no settings are assumed. 
The tabbing specified takes effect with the next line processed, 
not the line containing the TAB directive. 

If it is omitted, no tab settings are used. 
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FMT 



Tab settings that are deleted for the indicated tab_character. 
Use the following format to specify this parameter: 

'tab_character', integer {, integer }... 

The tab_ character is from 1 to 8 characters. This directive 
deletes the tab settings specified for the indicated tab_ 
character. For example, if the following CLEARTAB parameter 
was specified following the sample TAB parameter shown 
earlier, 

?? fmt (cleartab:= '{', 5) ?? 

the formatter would no longer move to the fifth column when 
it encountered a left brace. Instead it would us° the remaining 
tab setting (as set by the TAB parameter described earlier) and 
move to the twentieth column. 

ALL can be used in place of the integers to indicate that all 
tab settings should be deleted for the specified tab character. 

The tabbing specified takes effect with the next line processed, 
not the line containing the CLEARTAB directive. 

INDENT 

Number of columns to indent when a block-type statement is 
found. (These statements are BEGIN, FOR, REPEAT, WHILE, 
IF, and CASE; they are described in chapter 5.) This value is 
specified as an integer from to 20. If it is omitted, two 
spaces is assumed. This indentation value does not apply to 
lines that are continued; continued lines are indented six 
spaces. 

Example: 

The following FMT directive causes formatting to be done without 
compressing successive space characters and setting tab positions at 
columns 1, 10, and 40 for the left brace character: 

?? fmt (formation, compress:= off, tab:='{',1, 10, 40) ?? 
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LEFT Directive 

The LEFT directive specifies the left margin used for the formatted 
output. In effect, this directive determines the base left margin from 
which all positioning and indenting take place. The source being used 
from the input file is not affected by this directive; only the output is 
affected. 

Use this format for the LEFT directive: 

LEFT := integer 

integer 

The column number of the left margin. The left margin must 
be greater than zero. 

If you don't use the LEFT directive, the left margin of the formatted 
output is assumed to be column 1. 

The LEFT directive can also be used during compilation (that is, 
following the CYBIL command) to indicate that all source text left of 
the left margin is ignored. 

Example: 

The following example sets the left margin of the formatted output at 
column 10 and the right margin at column 100. This means that the 
positioning and indenting of lines is based on an initial left margin of 
10; for example, an indentation of 2 .spaces moves the line to column 
12. The maximum line width allowed in the formatted output using 
this example would be 90 characters. 

?? left := 10 right := 99 ?? 
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RIGHT 



The RIGHT directive specifies the right margin used for the formatted 
output. In effect, this directive determines the line width used by the 
formatter. The source being used from the input file is not affected by 
this directive; only the output is affected. 

Use this format for the RIGHT directive: 

RIGHT := integer 

integer 

The column number of the right margin. The right margin 
must be greater than or equal to the left margin plus 10, and 

less thai nr pmial tn 1 1 fl fVint io- 

left margin + 10 ^ right margin ^100 

The line width of the formatted output can also be set on the 
FORMAT_CYBIL_SOURCE command. If so, the RIGHT directive 
overrides that value when it is encountered. If neither the FORMAT_ 
CYBIL_ SOURCE command nor the RIGHT directive specify line 
width, the right margin is assumed to be column 79. 

The RIGHT directive can also be used during compilation (that is, 
following the CYBIL command) to indicate that all source text right of 
the right margin is ignored. 

Example: 

The following example sets the left margin of the formatted output at 
column 10 and the right margin at column 100. This means that the 
positioning and indenting of lines is based on an initial left margin of 
10; for example, an indentation of 2 spaces moves the line to column 
12. The maximum line width allowed in the formatted output using 
this example would be 90 characters. 

?? left := 10 right := 99 ?? 
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using tne Lie Dug utility y 



Introduction to Debug 

i^eoug is an oC/ij command utility cna^ lets you ueoug a program 
during execution. Using Debug, you can stop execution at selected 
points, display the values of selected variables, and resume execution. 

Debug requires no modification of your source code and no knowledge 
of assembly language. You can reference variables by their symbolic 
names rather than their addresses in memory. Furthermore, you do 
not need to interpret memory dumps or use a load map. 

Debug can be used in line mode or screen mode. You can use Debug 
to perform machine-level debugging as well as symbolic debugging. 
This discussion focuses on using screen mode Debug for symbolic 
debugging. For information about line mode Debug, machine-level 
debugging, and other Debug features, see the Debug Usage manual. 

Screen mode Debug gives you all of the Debug features with the ease 
of a full screen interface. You can execute Debug functions by 
pressing function keys rather than typing commands. Online HELP 
enables you to learn screen mode Debug as you use it. 

Using the Debug utility in screen mode, you can: 

• View your source code as it executes (an arrow points to the next 
line to be executed). 

• Change the values of program variables while execution is 
suspended. 

• Change the location where execution of your program resumes. 

• View module components of your program. 
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Getting Started 

I Getting Started 

| Using Debug in screen mode requires that your terminal support full 

| screen operation. If your terminal is not set up for full screen 

| operation, see the SCL System Interface manual for terminal 

I definitions that support the full screen interface. 

| To execute your CYBIL program with Debug and use the symbolic 

| debugging capability, you must compile the program with the 

I OPTIMIZATION. LEVEL (OL) and DEBUG_AIDS (DA) parameters 

| specified. Furthermore, to use Debug in screen mode, you must enter 

| the command: 

CHANGE_INTERACTION_STYLE STYLE=SCREEN 

| For example, to prepare the source program TEST_CYB contained in 
I permanent file $USER.TEST_CYB for use with Debug, enter the 
I following commands: 

/change_interaction_style style=screen 
/cybil input=$user.test_cyb binary=lgo .. 
. ./opt i mi zation_ level =debug debug_aids=al l 

or abbreviated, 

/chais s=s 

/cybil i=$user.test_cyb b=lgo ol=debug da=all 

I To execute TEST_CYB with screen mode Debug, enter the following 
1 command: 

| /execute_iask file=igo debug_mode=on 

1 or abbreviated, 

/exet f=lgo dm=on 

| On a Zenith Z19 or Heathkit H19 terminal the TEST_CYB source 
| module is displayed as follows. (On other terminals, the screen format 
| may vary slightly.) 
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Getting Started 



v2 : 






Displaying 


Routines 


SOURCE LIST OF modulejnain; 





1 


MODULE module main 





2 







3 


PROCEDURE [ZREFj p (operandi. 





4 


operand2: integer; 





5 


VAR result: integer; 


mi o 


6 


VAR status: boolean); 





7 







8 


PROGRAM main; 





9 







10 


VAR 


4 


11 


i, 


4 


12 


J, 


4 


13 


k: [STATIC] integer, 


4 


14 


x, 


4 


15 


y, 


4 


16 


z: insger , ' 


4 


17 


b: boolean I 



OUTPUT 

— Welcome to Full Screen Debugging 

Press HELP for assistance 



i m- - — 

! I 


I ! 


I I Locate ! 


I 


! IDelBrkl 


I 


Deas 


I 


ZmOut! 


I 


Keys ! 




i m 


[ f3|HSpeedl 


f4! 


I f5ISetBrk| 


fBI 


Quit 


f7| 


Trace I 


f8! 


I 



i Home line 



35 Response line 



Source window 



% Output window 



Figure 9-1. Debug Screen 

The line on which you enter Debug 
commands and SCL commands. 

The line on which short responses and 
advisory messages from Debug are 
displayed. 

The area in which the program you are 
debugging is displayed. 

The area in which the output generated by 
your program (or output delivered by 
Debug) is displayed. 



Row of function key The Debug functions assigned to function 
assignments keys. Also, you can enter Debug commands 

on the home line. 
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How to Get Help 

How to Get Help 

There are two ways to get help information while using the Debug 
utility in screen mode: 

1. The HELP key. 

Pressing the HELP key displays the help window. The help 
window overlays a portion of your screen and prompts you to enter 
the item for which you need help. If you press a function key, a 
short description of the function you select is displayed in the help 
window. To exit HELP, press RETURN. Upon exiting HELP, your 
screen is restored to its original contents. 

2. The EXPLAIN command. 

You can request help by entering the explain command on the 
HOME line. This command is used to read an online manual while 
you are debugging your program. To leave the online manual, 
press QUIT. When you leave the online manual, the screen is 
restored to its contents before you called EXPLAIN. For example, 
if you need information about Debug capabilities, press the HOME 
key and type the following EXPLAIN command on the HOME line: 

explain s='capabilities' m=debug 

This command takes you to the Debug online manual for an 
explanation of Debug capabilities. To return to screen mode Debug, 
press QUIT. See the SCL System Interface manual for more 
information about EXPLAIN. 
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example 

This example demonstrates some commonly used Debug functions. It is 
represented as a series of steps. To get the most benefit from this 
example, you should create the sample program, EXAMPLE_CYB, 
illustrated in figure 9-2 then perform each step. 

EXAMPLE_CYB is divided into the following test cases: 

TEST1 A loop that increments a counter and then calls a procedure 
to square and display the count. TEST1 demonstrates the 
use of the CHAVAL, GOTO, HSPEED, SEEVAL, STEP1 and 
STEPN functions. 

TEST2 A loop that builds a 6-row table of 3-character strings. Input 
to the table is an 18-character list for the months JAN 
through JUN. TEST2 moves three characters at a time from 
the character list to the table, and displays each entry. 
TEST2 shows how to step through loops, use line mode 
Debug commands in screen mode Debug, and how to scroll 
through Debug and program output data. 

TEST3 A division test that results in a divide fault. TEST3 
demonstrates how Debug handles execution errors. 

In each test case, the application of some Debug functions is 
demonstrated. After you work this example, you can begin to debug 
your CYBIL programs using screen mode Debug. 
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Example 



MODULE example_cyb; 




{ Copy I/O procedures. } 


TYPE 




column = array [1..3] of string(3), 


twodim_array = array [1..6] of column; 


CONST 




maximum_record_length = 40; 


VAR 




{ Declare program variables. } 


divisor 


real := 0.0, 


dividend 


real := 100.0, 


quot i ent 


real , 


cntr 


integer, 


result 


integer, 


month 


twodim_array, 


month_list 


String (18) : = ' JANFEBMARAPRMAYJUN' , 


month_row 


integer := 0, 


length 


integer := 10, 


i 


integer, 


{ Declare variables 


for I/O. } 


lfn 


amt $ l oca 1 _f i l e_name , 


o 


amt$fi le_identif ier, 


s 


ost$status, 


f 


amt$f i 1e_byte_address, 


newl ine 


string (90), 


ml 


string (7) := ' times ', 


m2 


string (3) :='=', 


m3 


string (16) := ' The month is: ', 


m4 


string (19) := ' The quotient is: '; 



Figure 9-2. Example of an EXAMPLE _CYB Source Listing 

(Continued) 
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Example 

(Continued) 



PROGRAM main; 
{ These calls specify file attributes and open files. } 

lfn := '$OUTPUT'; 

amp$open (lfn, amc$record, NIL, o, s); 



{ TEST1: Add to counter and call procedure SQUARE to square } 
{ and display count. } 

FOR cntr := 1 TO 10 DO 

square (cntr, result) ; 

stringrep(newline, length,' ',cntr:3,m1 ,cntr :3, 

m2, result :4); 
amp$put _next ( o , * new 1 i ne , max i mum_r ecor d_ 1 engt h , 
f.s); 
FOREND: 



{ TEST2: Create single column table for each month. } 

WHILE month.row < 6 DO 

FOR i := 1 TO 3 DO 

month[month_row][i ] :=month_list 
(month_row*3+1,3); 
FOREND; 

stringrep(newline, length, ' ' ,m3,month[month_row] 

[11:8); 
amp$put_next(o, "newl ine,maximum_record_ length, f,s) ; 
month_row := month_row + 1; 

WHILEND; 



Figure 9-2. Example of an EXAMPLE _CYB Source Listing 

(Continued) 
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Example 

(Continued) 

{ TEST3: Create divide fault. } 

quotient := dividend / divisor; 

st r i ngrep(new1 i ne , 1 ength , ' ' ,m4 : 19 , quot i ent :6 : 1 ) ; 

amp$put _next ( o , " new 1 i ne , max i mum_r ecor d_ 1 engt h , f , s ) ; 

PROCEND main; 

{ Procedure for squaring numbers. } 

PROCEDURE [XDCL] square ( 
a : integer; 
VAR b : integer; 

b := a * a; 

PROCEND square; 

MODEND example_cyb; 



Figure 9-2. Example of an EXAMPLE _CYB Source Listing 



9-8 CYBIL Language Definition Revision F 

W | 01/22/87 19:59:24 | 02/13/87 09:46:31 | 87/03/25 22.17.32 | 60464113 F I USING DEBUS I DRAFT COPY 



Preparing to Debug 

Preparing to Debug 

After you create EXAMPLE_CYB, you must prepare it for use with 
screen mode Debug. This requires preparing the screen mode 
environment and compiling EXAMPLE _CYB for use with Debug. You 

rton f It a it flvfl/>ii+a if mtrlAi* CWDOTI TVirtdc T^fiVm rf /■»*"» •M+"i*ri1 T"W\ +Vi"ie QC 

follows: 

1. EXAMPLE _CYB calls several file interface procedures that must 
be expanded through commands provided in the Source Code 
Utility (SCU) before the source code can be compiled. To do this, 
enter the following commands: 

/create_source_library 

/scu_create_deck deck=example_cyb modi fi cat ion =ml .. 

. ./source=$user .example_cyb 

/scu_expand_deck deck=example_cyb .. 

. ./alternate_base=$system.cybi 1 .osf$program_interface . . 

. ./compi 1e=$user .compi ie 

or abbreviated, 

/cresl 

/scu_cred d=example_cyb m=m1 s=$user.example_cyb 

/scu_expd d=examp l e_cyb .. 

. ./ab=$system.cybi 1 .osf$program_interface . . 

. . /c=$user . compi 1 e 

2. Prepare for screen mode debugging and compile EXAMPLE_CYB 
now contained in permanent file $USER. COMPILE for use with 
Debug by entering the following commands: 

/change_interaction_style style=screen 
/cybil input=$user. compile binary=lgo .. 
. . /opt i m i zat i on_ 1 ewe 1 =debug debug.a i ds=a 1 1 

or abbreviated, 

/chais s=s 

/cybil i =$user. compi le b=lgo ol=debug da=all 
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3. Execute under control of Debug by entering the following 
command: 

/execute_task file=lgo debug_mode=on 

or abbreviated, 

/exet f=lgo dm=on 

The EXAMPLE_CYB source module is displayed in the source 
window. Debug functions are displayed at the the bottom of the 
screen. 

Displaying Screen Mode Commands 

The functions below are used to display helpful information about the 
Debugging environment: 

HELP Displays the help window. Press a function key and a short 
explanation of the function's use appears in the Help window. 

ZMIN Used to display the source listing in the source window. 

Now perform the following steps to become familiar with the Debug 
functions: 

1. Press the HELP key. The help window is displayed. 

2. Press each function key corresponding to the functions displayed at 
the bottom of the screen. As you press each function key, a short 
explanation of the purpose of each function is displayed in the 






3. Press RETURN. This exits HELP and the help window is removed. 



il rriffTTLT /» 



t. i-ress me ^iviiin iuncnon Key. ine ionowmg message is displayed 
in the upper right hand corner of the screen: 

Enter compiler input file for EXAMPLE_CYB 



9-10 CYBIL Language Definition Revision F 

W | 01/22/87 19:59:24 | 02/13/87 09:46:31 | 87/03/25 22. 17.32 | 60464113 F | USING DEBUG | DRAFT COPY 



Preparing to Debug 



o. unter me source me name: 



$user .compi le 



The EXAMPLE_CYB source listing is displayed in the source 
window. Also, some new functions are displayed at the bottom of 
the screen. 

6. Press the HELP key. The help window is displayed again. 

7. Press each function key corresponding to the new functions 
displayed at the bottom of the screen. As you press each function 
key, a short explanation of the purpose of each new function is 
displayed in the help window. 

Setting Breaks 

It is often helpful to suspend program execution when debugging a 
program. The Debug device for suspending execution of a program is 
called a break. In this sample session, the following functions are 
used to illustrate setting breaks. 

Function Result 

BKW Scrolls backward to the previous screen of text. 

FWD Scrolls forward to the next screen of text. 

LOCATE Prompts you to type in text, then searches the source 

listing for matching text. If a match is found, the cursor 
is moved to the line containing the matching text. 

SETBRK Sets an execution break on the line containing the cursor. 
The line is highlighted to show that it contains a break. 
Execution is suspended before the line containing the 
break is executed. Execution resumes with the first 
statement on the line containing the break. 
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Perform the following steps to place three execution breaks in 
EXAMPLE_CYB: 

1. Press the LOCATE function key. At the top right hand corner of 
the screen, you are prompted for the text to be located. 

2. Enter the following text exactly as it appears in EXAMPLE_CYB: 

WHILE 

The cursor is moved to the line: 
WHILE month_row < 6 DO 

3. Press the SETBRK function key. A break is set and the line 
containing the cursor is highlighted to show that it contains an 
execution break. 

4. Use the down-arrow key to move the cursor to the line: 

month_row := month_row + 1; 

If you do not see this line on your screen, press the FWD key. 
The next screen of the EXAMPLE_CYB source listing is 
displayed. Use the down-arrow key to position the cursor on that 
line. 

5. Press the SETBRK function key. The line is highlighted to show 
that it contains an execution break. 

6. Press the FWD function key. The next screen of the EXAMPLE_ 
CYB source listing is displayed in the source window. 

7. Use the down-arrow key to move the cursor to the line: 

quotient := dividend / divisor; 

8. Press the SETBRK function key. The line is highlighted to show 
that it contains an execution break. 

9. Press the BKW key two times. The first screen of the 
EXAMPLE_CYB source listing is displayed in the source window. 
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Debugging Testl 

Debugging Testl 

Using Debug, you can execute a program one statement or several 
statements at a time. Also, you can examine a variable's contents, 
change its contents, and execute code containing the variable several 

fimoc 'PVmce na-naKlllt.TP^ flfp rlomnnefra+n/3 in t.Vilc cpmnlp coccinn 

using the following functions: 

CHAVAL Prompts you to enter a variable name and the value 

you want it to contain, then changes the variable's 
contents to the new value. 

GOTO Moves the execution pointer to the line that contains 

the cursor. Execution resumes with the first statement 
on this line. 

HSPEED Executes a program until a break is encountered or the 

program ends. 

SEEVAL Prompts you to enter a variable name, then displays 

the value of the variable in the output window. 

STEP1 Executes a program one statement at a time. 

STEPN Executes N statements of a program, where N is an 

integer. 

Perform the following steps to demonstrate the use of the CHAVAL, 
GOTO, HSPEED, SEEVAL, STEP1, STEPN: 

1. Press the STEP1 function key. The statement: 

lfn := '$0UTPUT'; 

is executed; the execution arrow now points to the statement: 
amp$open( lfn,amc$record,NIL,o,s) ; 

2. Press the STEP1 function key again. The amp$open procedure is 
executed; moving the execution arrow to the first executable line 
in TEST1: 

FOR cntr := 1 TO 10 DO 
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| 3. Press the STEP1 function key seven times. An iteration of FOR 
| loop is executed one statement at a time. The output from the 

iteration is displayed in the output window. 

| 4. Press the SEEVAL function key. A prompt to enter a variable 
name is printed in the upper right hand corner of the screen. 
Enter the name: 

cntr 
The value of CNTR is displayed in the output window: 

cntr = 2 

Thus, you can use SEEVAL, to examine the contents of a variable. 

5. Press the CHAVAL function key. A prompt for a variable name 
| and its new value is displayed in the upper right hand corner of 

| the screen; enter: 

cntr =8 

I The value of CNTR is changed to 8. 

I 6. Press the SEEVAL function key. When you are prompted for a 
1 variable name, enter: 

cntr 

The following message is displayed in the output window: 

cntr = 8 

I Thus, the change of value for CNTR is verified. 
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i. fress tne siiiriN iunction Key. in tne upper rignt nana corner 01 
the screen, you are prompted for the number of lines to execute; 
enter: 



STEPN executes 6 lines. The output from this loop iteration is 
displayed in the output window. 

8. Press the SEEVAL function key. When you are prompted for a 
variable name, enter: 

cntr 

The value of COUNTER is displayed in the output window: 

cntr = 3 

Only the value of CNTR passed to the SQUARE call was changed. 
The value of a FOR loop control variable cannot be changed once 
the loop has been entered. Therefore, the value of CNTR used by 
this FOR loop remains unchanged. 

9. Use the up-arrow key to move the cursor to the line: 

FOR cntr := 1 TO 10 DO 

10. Press the GOTO function key. The execution arrow moves to the 
line containing the cursor; execution resumes at this line. 

11. Press the HSPEED function key. Execution resumes from the FOR 
statement. Since the FOR loop is executed anew, CNTR is 
initialized to 1. Execution of EXAMPLE _CYB continues until an 
execution break is encountered. 
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Debugging Test2 

After program execution is resumed in step 12 of TEST1, execution 
stops at the break set on the first statement in TEST2. The following 
functions are used in TEST2 to illustrate more Debug capabilities: 

BKW Scrolls backward to the previous screen of text. 

CHAVAL Prompts you to enter a variable name and the value 

you want it to contain, then changes the variable's 
contents to the new value. 

DELBRK Deletes execution breaks. 

FWD Scrolls forward to the next screen of text. 

HSPEED Executes a program until a break is encountered or the 

program ends. 

SEEVAL Prompts you to enter a variable name, then displays 

the value of the variable in the output window. 

This section also uses the following features: 



HOME 



DISPLAY. 
PROGRAM- 

_ VALUE 



Press the HOME key to move the cursor to the HOME 
line, line mode Debug commands can be entered on the 
HOME line for execution in screen mode Debug. 

A line mode Debug command that displays the values 
of program variables. 
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Perform the following steps to learn how to execute loops one 
iteration at a time, execute line mode Debug commands, and scroll 
output data when using Debug: 

1. Press the HSPEED function key. Execution stops at the break set 
on the last line of the WHILE loop; output from the loop is 
displayed in the output window. 

2. Press the HSPEED function key again. One iteration of the 
WHILE loop is executed; execution stops at the break set in the 
WHILE loop again. Each time HSPEED is used, an iteration of 
the loop is performed. By using strategically placed execution 
breaks, as in this example, a loop can be executed one iteration at 
a time. 

3. Press the HSPEED function key. One more loop iteration is 
performed. 

4. Press the SEEVAL function key. When you are prompted, enter: 

month_row 
The following message is displayed in the ounput window: 
month_row = 2 

5. Press the CHAVAL function key. When you are prompted, enter: 

month_row=4 

6. Press the SEEVAL function key. When you are prompted, enter: 

month_row 
The following message is displayed in the output window: 

month_row = 4 
Thus, the change to MONTH_ROW is verified. 
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7. Press the HSPEED function key. One iteration of the WHILE loop 
is executed. 

8. Press the SEEVAL function key. When you are prompted, enter: 

month_row 

the following message is then displayed in the output window: 

month.pow = 5 

The value given to MONTH _ ROW in step 5 is used by the 
WHILE loop. 

9. Press the HOME key. The cursor moves to the HOME line. 

10. Enter the line mode Debug command: 

display_program_ value name=$all 

The values of all variables declared in EXAMPLE _CYB are 
displayed in the output window. Thus, line mode Debug commands 
can be used in screen mode Debug by entering them on the 
HOME line. For more information about using line mode Debug 
commands see the Debug Usage Manual. 

11. Press the DELBRK key. The execution break is deleted. 

12. Press the down-arrow key until the cursor is inside of the output 
window. 

13. Press the BKW key. The data in the output window scrolls 
backward. When the cursor is contained within the output window, 
you can use the BKW and FWD keys to scroll backward and 
forward through the data in the window. 

14. Press the HSPEED function key. The execution of EXAMPLE_ 
CYB resumes, stopping at the next break. The execution arrow 
points to the first statement in TEST3. 
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liebugging Testa 



After resuming execution of EXAMPLE_CYB in step 14 of section 
TEST2, execution stops at the begining of TEST3. In TEST3, Debug is 
presented with an execution error. The following functions are used in 
this sample session to demonstrate how Debug can be used when an 
execution error is encountered: 

CHAVAL Prompts you to enter a variable name and the value 

you want it to contain, then changes the variable's 
contents to the new value. 

GOTO Moves the execution pointer to the line that contains 

the cursor. Execution resumes with the first statement 
on this line. 

SEEVAL Prompts you to enter a variable name, then displays 

the value of the variable in the output window. 

STEP1 Executes a program one statement at a time. 

OTTTT TTcqH *t> loo™ TVKun 

Perform the following steps to finish the example: 

1. Press the STEP1 function key. Execution halts, and the following 
message flashes in the top right hand corner of the screen: 

divide_fault 

2. Press the SEEVAL function key. When you are prompted for a 
variable name, enter: 

divisor 
The following message is displayed in the output window: 

divisor = 0. 
A division by zero caused the execution error. 
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I 3. Press the CHAVAL function key. When you are prompted, enter: 

divisor=1.0 
I The value of DIVISOR is changed to 1. 

| 4. Press the SEEVAL function key. When you are prompted, enter: 

divisor 

The following text is displayed in the output window: 

I divisor=1 .OO00000O0O00OOE+00O0 

1 The change to DIVISOR is verified. 

| 5. Press the GOTO function key. The execution arrow points to the 
DIVISION statement, so program execution resumes with this 
statement. 

I 6. Press the STEP1 function key. The DIVISION statement is 

executed. Therefore, the GOTO and CHAVAL functions can be used 
in concert to recover from execution errors. However, to correct 
execution errors permanently, you must exit Debug, edit the 
program, and recompile it. 

| 7. Press the STEP1 function key two more times. The result of the 
DIVISION statement is displayed in the output window. 

| 8. Press the STEP1 function key. EXAMPLE_CYB ends and the 
following message is. displayed in the output window: 

DEBUG: The status at termination was: NORMAL. 

I 9. Press the QUIT function key. Exit Debug. 

| Now that you have concluded this example, you should be able to 

| begin using screen mode Debug to debug your CYBIL programs. For 

| more information about screen mode Debug and line mode Debug 

1 commands, see the Debug Usage manual. 
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Part II. Common CYBIL Input/Output 

How to Use Common CYBIL I/O 10-1 

Opening, Closing, and Structuring Files 11-1 

Reading and Writing Files 12-1 

NOS/VE-Specific Procedures and Functions for CYBIL I/O 13-1 
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This chapter explains how to use CYBIL I/O and describes the 
features and limitations that are unique to the NOS/VE 
implementation of CYBIL I/O. 

Introduction 10- 

Using CYBIL I/O Procedures 10- 

Copying Procedure Declaration Decks 10- 

Expanding a Source Program 10- 

Calling a CYBIL I/O Procedure 10- 

Parameter List 10- 
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rjA-tracLing oioiij rroteaure i/eciis iu- 

Parameter Types 10- 

VAR Parameters 10- 

Checking the Completion Status 10- 

Status Condition Codes 10- 

oystem i>anung convention 10- 

Procedure Call Description Format 10- 

Parameter Description Format 10- 

Features Unique to NOS/VE 10- 

Copying Procedure Declaration Decks in Bulk 10- 

File Names 10- 

Position of File When Opened 10- 

Position of File When Closed 10- 

File Attributes 10- 

File Structure 10- 
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Introduction 

I/O) allow a CYBIL program to use the input/output capabilities of 
NOS/VE, principally for reading and writing files. CYBIL I/O is not 
designed specifically for NOS/VE, but is standardized for use on 
several operating systems (NOS/VE, NOS, NOS/BE, VSOS, EOS, and 
APOLLO Aegis I/O systems). If CYBIL I/O were implemented on these 
systems, CYBIL programs that use CYBIL I/O procedures could 
execute on any of these operating systems with little or no 
modification. Currently, however, CYBIL I/O is only available for 



NOTE 

Display screen interfaces and the more sophisticated input/output 
capabilities of NOS/VE are beyond the scope of Common CYBIL I/O. 
For these, refer to the CYBIL File Management manual, the CYBIL 
Sequential and Byte-Addressable Files manual, and the CYBIL 
Keyed-File and Sort/Merge Interfaces manual. 



CYBIL I/O procedures may be used for either disk or terminal 
input/output, and with either disk or tape files. 1 

The CYBIL I/O procedures and data types are stored in the NOS/VE 
program interface; they can be used in a CYBIL program but are not 
part of the CYBIL language as such. In brief, the components are the 
following: 

• CYBIL procedures and functions, both standard and 
NOS/VE-dependent. 

• CYBIL constants, variables, and data-types used within the 
procedures and functions. 



1. When using CYBIL I/O with tape files, note the following: tape marks cannot be 
read or written, and tape files cannot be read in reverse. 
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• Exception conditions issued by CYBIL I/O. 

These components employ the basic elements of the CYBIL language 
described in Part I of this manual: constants, variables, types, 
functions, and procedures. For a description of the general format of 
these CYBIL elements, refer to Part I of this manual. Part II, CYBIL 
Input/Output, describes the specific components of CYBIL I/O and 
explains how to use them in CYBIL programs. 

Part II is made up of the following chapters: 

• Chapter 10, How to Use Common CYBIL I/O, explains how to use 
CYBIL I/O procedures in a CYBIL program and describes the 
features and limitations that are unique to the NOS/VE 
implementation of CYBIL I/O. 



• 



• 



Chapter 11, Opening, Closing, and Structuring Files, which 
describes the procedures for performing these activities. 

Chapter 12, Reading and Writing Files, describes each of the 
procedures for reading and writing files with CYBIL I/O, and 
contains examples of CYBIL programs using CYBIL I/O. 

Chapter 13, NOS/VE-Specific Procedures and Functions for CYBIL 
I/O, describes the procedures and functions that can only be used 
with the NOS/VE implementation of CYBIL I/O. 

Appendix J lists the constants and data types used by CYBIL I/O, 
and Appendix K lists the CYBIL I/O error messages. 
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Using CYBIL I/O Procedures 
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Each CYBIL I/O procedure resides as an externally referenced (XREF) 
declaration in a deck on the following source library file: 

$SYSTEM.CYBIL.OSF$PROGRAM_INTERFACE 

The XREF procedure declarations for the keyed-file calls described in 
the CYBIL Keyed-File and Sort/Merge Interfaces manual are stored as 
decks in the source library file 
$SYSTEM.COMMON.PSF$EXTERNAL_INTERFACE_SOURCE. 

To use a CYBIL I/O procedure, you must include the following 
statements in your CYBIL source program: 2 

n. ouuikc v/uuc uuiity ^3ou; V/vat Iv u-u.eiibi.v6 xOl uOpjuiig uuc 

XREF declaration from the source library 
$SYSTEM.CYBIL.OSF$PROGRAM_INTERFACE. 

• Statements that declare, allocate, and initialize actual parameter 
variables as needed. 

• The procedure call statement. 

• An IF statement that checks the procedure completion status 
returned in the procedure's status variable. 

Figure 10-1 lists a source program that illustrates the use of these 
CYBIL I/O procedures. 



2. In the rest of this chapter, the term procedure is used in the broader sense of a 
subroutine or set of instructions which can be executed by a single statement. It 
therefore refers to both procedures and functions as described in Part I. 
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MODULE examplel; 

{ Directive to copy the XREF procedure declaration.} 

•copyc cyp$get_next_record 

{ This procedure reads the next record from a file } 

{ that was opened as a record file and returns a status } 

{ record to the caller.} 

PROCEDURE get _next .record 
(record_f i le: cyt$file; 
pointer_to_target : "SEQ ( * ); 
VAR number_of _ce l 1 s_read : integer; 
VAR status: ost$status); 

{ Procedure call statement } 

CYP$GET_NEXT_RECORD (record.fi le, pointer_to_target , 
number_of_cel ls_read, status) ; 

{ Status record check. } 

IF NOT status. NORMAL THEN 

RETURN; 
IFEND; 



PROCFND gp+_next_record; 
MODEND examplel; 



The following paragraphs describe in greater detail the SCU directives 
and CYBIL statements required for using CYBIL I/O procedures. 
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To use a CYBIL I/O procedure in a CYBIL module, you must include 
in the module an SCU *COPYC directive to copy the procedure's 
CYBIL XREF declaration from the source library file 
$SYSTEM.CYBIL.OSF$PROGRAM_INTERFACE. 

The deck containing the procedure declaration has the same name as 
the procedure, For example, the CYP$GET_NEXT_RECORD 
procedure is declared in a deck named CYP$GET_NEXT_RECORD. 

The *COPYC directives begin in column one and specify the name of 
the deck to be copied. In figure 10-1, they follow the MODULE 
statement. 

Regardless of how many times a procedure is called, you need only 
one *COPYC directive per procedure. (For more information about the 
*COPYC directive, see the SCL Source Code Management manual.) 

Procedure declaration decks list the parameters and their valid CYBIL 
types, which must be listed on a call to a CYBIL I/O procedure. When 

« rtVDTT ■ n ~* > ~«. nv vt I* U^vt/v A^-tv^^lfl 4-Urt nnfnmntAW ,i-r* +Vi£> Anil in ilm 
Ci V> i AJii-i pi.OgiO.iil -i» UCLiig ^Ijiilp-LIGU, bliC fc/CLL CLiilC IfCl B Uii ifiiC \*Cii.L LU U.1C 

procedure are verified with the parameters and parameter types listed 
in the procedure's XREF declaration. If they do not match, the 
program compilation fails. After the module in figure 10-1 is expanded 
and compiled, the XREF procedure declaration is included in the 
source listing. 

For an example of a procedure declaration deck, refer to Extracting 
CYBIL Procedure Decks later in this chapter. 

In chapters 11, 12, and 13, the parameters and each parameter's 
required type are listed in the individual description for each CYBIL 
I/O procedure. In addition, the parameter types for all CYBIL I/O 
procedures are listed alphabetically in Appendix J of this manual. 

Expanding a Source Program 

Before you can compile a source program containing one or more 
CYBIL I/O XREF procedures, you must first expand your source 
program. (Expanding a program generates the source code to be 
compiled.) You can use the SOURCE. CODE _ UTILITY (SCU) 
subcommands to do this, or you can use the SCL command EXPAND_ 
SOURCE. FILE. 
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The following SCL statements illustrate the way to use the SCL 
EXPAND_ SOURCE _ FILE command to expand a source program. 

/expand_source_f i 1 e , f i 1 e=my_program . . 

. ./alternate_base=($system.cybi 1 .osf$program_interface, . . 

. ./$system. common. psf$external_interface_source) 

The command writes the expanded text on the default file, COMPILE. 
You then compile the expanded program text with the following: 

/cybil input=compile list=listing 1 ist_options=(r, a) 

The EXPAND_SOURCE_FILE example, above, shows the steps 
required to expand the CYBIL source program contained in figure 
10-1. Spelled out, the steps consist of the following: 

• Specify the name of the file to be expanded on the FILE 
parameter. 



• 



• 



Specify the $SYSTEM.CYBIL.OSF$PROGRAM_INTERFACE file on 
the ALTERNATE_BASE parameter. This file contains the XREF 
procedure decks for all CYBIL I/O procedures. If the CYBIL 
program uses one of the keyed-file procedures, the file 
$SYSTEM.COMMON.PSF$EXTERNAL_INTERFACE_SOURCE 
must also be specified on the ALTERNATE _ BASE parameter. The 
file is then expanded, and the XREF decks named on *COPYC 
directives in the CYBIL module are copied into the expanded 
source program. By default, the name of this expanded source 
program is COMPILE. 

Call the CYBIL compiler to compile the source program on file 
COMPILE, and write a source listing on file LISTING. The list 
options available on the CYBIL statement are described in Part I 
of this manual. 
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Calling a (JYBIL I/O Procedure 

A call to a CYBIL I/O procedure has the same format as any CYBIL 
procedure call: 



For more information on CYBIL procedure calls, see Part I of this 
manual. 

Parameter List 

The parameter list provides the procedure with input values and the 
locations at which it is to store output values. You can specify an 

input vcimw cib7 1/11& vaiu& iwgu \#a citj tt Tttiiuuit vuuuaiiiiiig uixw tuiu&. 

NOTE 

All parameters on a procedure call are required. You must specify a 
value or variable for each parameter in the parameter list. 

CYBIL performs type checking on the variables and values specified 
in the parameter list. It compares the parameters on the procedure 
call with the parameter types listed in the XREF procedure 
declaration. Therefore, to make a successful call to a CYBIL I/O 
procedure, the parameters on the procedure call must conform to the 
parameter types specified in the procedure declaration deck. 

Type checking and the valid parameter types for CYBIL programs are 
discussed in Part I of this manual. 

Extracting CYBIL Procedure Decks 

As mentioned earlier, the procedure declaration decks for all CYBIL 
I/O procedures are contained in the 

$SYSTEM.CYBIL.OSF$PROGRAM_INTERFACE library file. You can 
display a particular deck in this file for your own information by 
using the SCU subcommand EXTRACT_DECK, which extracts a deck 
and writes it to a file. The contents of each deck are identical to the 
parameters and types listed in each procedure call description in this 
manual. 

The following example shows how to extract the CYP$GET_NEXT_ 
RECORD procedure declaration deck and display it at your terminal. 
By default, the extracted deck is written to file SOURCE. 
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/source_code_ut i 1 i ty 

sc/extract_deck deck=cyp$get_next_record . . 
sc. ./ab=$system.cybi l .osf$program_interface 
sc/edit_file source 

PROCEDURE [XREF] cyp$get_next_record 
(record_f i le : cyt$file; 
pointer_to_target : ~SEQ ( * ); 
VAR number_of _cel l s_read : i nteger ; 
VAR status: ost$status); 

?? PUSH (LISTEXT := ON) ?? 

•COpyc CYT$FILE 

*copyc OST$STATUS 

*COpyc CYE$EXCEPTION_CONDITIONS 

?? POP ?? 

sc/quit 

Parameter Types 

As indicated by the procedure declaration deck displayed above, a call 
to the CYP$GET_NEXT_RECORD procedure must specify four 
parameters in its parameter list. 

• The first parameter must specify a file identifier of type 
CYT$FILE. 

• The second must specify a pointer of type "SEQ. 

• The third must specify a variable of type integer. 

• The fourth must specify a variable of type OST$STATUS. 

VAR Parameters 

The procedure call descriptions in this manual and the XREF 
procedure declaration decks both contain parameters that have a VAR 
listed with the parameter. The VAR indicates that the parameter is 
treated as an output parameter by the procedure; that is, a value is 
returned to the parameter by the procedure. 

For example, the VAR listed with each procedure's status parameter 
indicates that the procedure returns a value to the status parameter. 
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T i 1 



in tne procedure declaration decs, me vajx precedes tne parameter 
name. 

VAR StatUS: OSt$StatUS; 



In the procedure call descriptions in this manual, the VAR is listed 
with the parameter's type. 

status: VAR of ost$status; 

For more information on declaring and assigning values to variables, 
see Part I of this manual. 

Checking the Completion Status 

The last parameter on a CYBIL I/O procedure call must be a status 
variable (type OST$STATUS). Unlike the status parameter on SCL 
commands, the status parameter on these CYBIL calls is required, not 
optional. When the procedure completes, NOS/VE returns the 
completion status of the procedure in the specified status variable. 

The program should check the completion status returned immediately 
after the procedure call. If the NORMAL field of the status variable is 
TRUE, the procedure completed normally. If the NORMAL field is 
FALSE, the procedure completed abnormally. 

For example, the following program fragment uses a status variable 
named STATUS. Immediately after the CYP$GET_NEXT_ RECORD 
call, an IF statement checks the value of the boolean field of the 
status record (STATUS. NORMAL). If its value is FALSE (NOT 
STATUS.NORMAL), the procedure terminates. 

cyp$get_next_record (record_f i le, pointer_to_target , 

number _of_ce11s_ read, status); 
IF NOT St at US. NORMAL THEN 

RETURN; 
I FEND; 

Status Condition Codes 

When the procedure terminates abnormally, NOS/VE returns 
additional information about the condition that occurred. The following 
fields of the record return this information when the NORMAL field 
is FALSE: 
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condition 



Exception condition code that uniquely identifies the condition 
(integer of type OST$STATUS_CONDITION_CODE). Each code 
can be referenced by its constant identifier as listed in the 
NOS/VE Diagnostic Messages manual. 

text 

String record (type OST$STRING) containing additional information 
about the condition. The record has the following two fields: 

size 

Actual string length in characters (0 through 256). 

value 

Text string (256 characters). 

NOTE 

The text field does not contain the error message. It contains items of 
information that are inserted in the error message template if the 
message is formatted using this status variable. 

If the NORMAL field of the status record is FALSE, the program 
determines its subsequent processing. For example, it might check for 
a specific condition in the CONDITION field or determine the severity 
level of the condition with an OSP$GET_STATUS_ SEVERITY 
procedure call. (The CYBIL System Interface manual contains the 
description of OSP$GET_ STATUS. SEVERITY and other condition 
processing calls.) 
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System Naming Convention 

All identifiers defined by the NOS/VE program interface use the 
system naming convention. The system naming convention requires 
that all system-defined CYBIL identifiers have the following format: 

i dx$name 



Field Description 

id Two characters identifying the product that uses the 

identifier. The following are the product identifiers referenced 
in this manual: 



Product 




Identifier 


Product Function 


AM 


Access method. 


CY 


CYBIL Input/Output 


FS 


File system. 


OS 


Operating system. 



Character indicating the CYBIL element type identified. 
x Description 





c 


Constant. 




d 


Deck. 




e 


Error condition. 




P 


Procedure. 




t 


Type. 


iek 


[ Description 



$ The $ character indicates that Control Data defined the 

identifier. 

name A string of characters describing the purpose of the element 
represented by the identifier. 
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For example, the identifier CYP$GET_NEXT_ RECORD follows the 
system's naming convention. Its product identifier is CY, for CYBIL 
Input/Output. The P following the product identifier indicates that it 
is a procedure name. The string GET_NEXT_RECORD describes the 
purpose of the procedure. 

Procedure Call Description Format 

Chapters 10 and 11 of this manual describe the CYBIL I/O 
procedures. Each description uses the following format and 
subheadings: 

Purpose Brief statement of the procedure function. 

Format Procedure call format showing the parameter positional 

order followed by individual parameter descriptions. 

Parameters Descriptions of the parameters in the preceding format, 
including the parameter's valid CYBIL type. 

Conditions List of condition identifiers returned by the procedure. 
The list is not complete; only the conditions that are 
likely to be of interest to the procedure user are listed. 

Remarks If present, additional information about procedure 

processing. 

Parameter Description Format 

Within a procedure description, each parameter description states the 
parameter's function, its values, and its valid CYBIL type. Appendix I 
of this manual contains an alphabetical listing of all parameter types 
for the CYBIL I/O procedures described in this manual. 

If the parameter type is a set of system-defined identifiers, the 
parameter description lists all possible identifiers in the set and their 
meanings. 

If the variable type is a record, the parameter description describes 
each field in the record. It states the field's name, its function, and its 

type. 
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Features Unique to JNUS/VJU 

The remainder of this chapter describes the features and limitations of 
CYBIL I/O on NOS/VE. 

Copying Procedure Declaration Decks in Bulk 

There are two ways to declare CYBIL I/O procedures in a CYBIL 
program. One way, already described, is to include the name of the 
procedure on the *COPYC directive, such as *COPYC GET_NEXT_ 
RECORD. With this method, there must be a *COPYC directive for 
each procedure used in the program. But another way, also using the 
*COPYC directive, is to declare the name of a deck which in turn 
declares all the CYBIL I/O procedures for a certain type of file, such 
as record files. Instead of a *COPYC directive for each of the record 
file procedures, one *COPYC directive would declare all of the record 
file procedures. The names of these general declaration decks and the 
procedures they declare are listed below. 

In order to declare these: Use this deck name: 

CYBIL I/O types CYT$CYBIL_INPUT_OUTPUT 

All procedures applicable to CYD$BINARY_FILE 

binary files 

All procedures applicable to CYD$RECORD_FILE 

record files 

All procedures applicable to text CYD$TEXT_FILE 
files 

All procedures applicable to CYD$DISPLAY_FILE 

display files 

For example, if a CYBIL program includes the following in its source 
code, 

'COPYC CYD$BINARY_FILE 

all the procedure declaration decks for the binary-file procedures 
described in chapters 12 and 13 are automatically copied into the 
source program during program expansion. 
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NOTE 



This method of declaring the binary-file procedures is efficient only if 
most or all of those procedures will actually be used by the program. 
If only a few are needed, it is better to declare them individually, 
because the CYD$BINARY_FILE declaration performs a tremendous 
amount of copying and would result in the needless use of system 
resources. 



File Names 

File names specified on the CYBIL I/O procedures which open files 
(such as CYP$OPEN_FILE) must conform to the naming conventions 
for NOS/VE, and are interpreted as file references. Within NOS/VE, 
file references include the path, cycle, and position of the file. 

! Position of File When Opened 

| You can specify the position at which a file is opened in one of 
I several ways: (listed in order of precedence) 

| • With the open_position record on the FILE _ SPECIFICATIONS 
parameter of CYP$OPEN_FILE (described in chapter 11). 

| • In the file reference (that is, on the file name) passed to 
| CYP$OPEN_FILE. 

I • With the SCL command SET_FILE_ATTRIBUTES. 

1 1. If the open_position record on the FILE_SPECIFICATIONS 

parameter specifies a file position, that position is used when the 
file is opened. 

I 2. If the open_position record does not specify a file position, then 
the file position included in the file reference on CYP$OPEN_ 
FILE is used. 

| 3. If the file reference does not include a file position, then the 

position specified on the SET_FILE_ATTRIBUTES command (if 
| specified for this instance of attachment) is used. 

I 4. If a file position has not been specified by the SET_FILE_ 

ATTRIBUTES command for this instance of attachment, then the 
* file's open position is beginning-of-information. 
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If you want the file opened at beginning-of-information, and if the file 
was not explicitly attached (with the ATTACH _ FILE command), then 
it is not necessary to specify any file position at all: 
beginning-of-information is automatically used when the file is opened 
with CYP$OPEN_FILE. If the file was explicitly attached, but no file 
position has been specified for this instance of attachment, it is 
likewise not necessary to specify any file position: 
beginning-of-information is automatically used. 

For a description of the CYP$OPEN_FILE procedure and the open_ 
position record of the FILE_SPECIFICATIONS parameter, refer to 
chapter 11. 

Position of File When Closed 

With the FILE_POSITION parameter of CYP$CLOSE_FILE 
(described in chapter 11), the caller can specify where a file is 
positioned before it is closed. This position is retained after the file is 
closed only if all of the following are true: 

• The file has been explicitly attached (with the ATTACH_FILE 
command). 

• The close_file_disposition record specified on the FILE_ 
SPECIFICATIONS parameter of CYP$OPEN_FILE is 
CYC$RETAIN_FILE. 

• Subsequent instances of open within the job specify an open_ 
position of CYC$ASIS. 

The open_position and close_file_disposition records are explained in 
chapter 11, under File Specification Records. 

File Attributes 

Because CYBIL I/O provides standard input/output interfaces for 
several operating systems, no provision is made to directly set or 
interrogate NOS/VE file attributes, except as described below. 3 

CYBIL I/O follows a simple set of rules for file attributes. 



3. At present, CYBIL I/O has only been implemented for NOS/VE. 
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• If the file has never been opened, the file is a new file and CYBIL 
I/O defines file attributes as listed in tables 10-1 and 10-2. If the 
FILE_SPECIFICATIONS parameter of the CYP$OPEN_FILE call 
contains a value from which the attribute may be set, that value 
is used. 

• If the file has been previously opened, CYBIL I/O considers the 
file an old file and does not modify or define any file attributes. 
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File, Attribute Binary Files 



Record Files 



file contents 

file structure 

file processor 

page format 1 

page length 1 
page width 1 



CYC$UNKNOWN_ 

CONTENTS 

CYC$UNKNOWN_ 
STRUCTURE 

CYC$UNKNOWN_ 
PROCESSOR 

CYC$BURSTABLE_ 
FORM 

60 lines 

132 columns 



CYC$UNKNOWN_ 
CONTENTS 

CYC$UNKNOWN_ 
STRUCTURE 

CYC$UNKNOWN_ 
PROCESSOR 

CYC$BURSTABLE_ 
FORM 

60 lines 

132 columns 



1. The attribute 
are for NOS/VE 



values for page format, 
files. 



page length, and page width 



Table 10-2. File Attributes for New Files: Text and Display 



File .Attribute 



Text Files 



Display Files 



file contents 
file structure 

file processor 

page format 1 

page length 1 
page width 1 



CYC$LEGIBLE 

CYC$UNKNOWN_ 
STRUCTURE 

CYC$UNKNOWN_ 
PROCESSOR 

CYC$CONTINUOUS. 
FORM 

60 lines 

132 columns 



CYC$LIST 

CYC$UNKNOWN_ 
STRUCTURE 

CYC$UNKNOWN_ 
PROCESSOR 

CYC$BURSTABLE_ 
FORM 

60 lines 

132 columns 



1. The attribute values for page format, page 
are for NOS/VE files. 



length, and page width 



You can define the page_length, page_ width, page_format, file_ 
contents, and file_processor attributes for new files on the FILE_ 
SPECIFICATIONS parameter of the CYP$OPEN_FILE procedure, 
which is described in chapter 11. 
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In addition, file attributes may be defined via SCL commands or 
CYBIL procedures prior to calling CYP$OPEN_FILE. In this case, 
CYBIL I/O considers the file an old file and does not define or modify 
any of the permanent attributes. 

File Structure 

Four kinds of files can be used with CYBIL I/O: binary, record, text, 
and display. All of these files have a beginning-of-information and an 
end-of-information. On NOS/VE, files can be further subdivided into 
partitions and records. (Binary files can only be subdivided into 
partitions.) 

Level Description 

Partition A partition begins either at the 

beginning-of-information or after the 
end-of-partition of the previous partition. 

Record A record begins at the beginning-of-information, 

after an end-of-partition, or after the 
end-of-record of a preceding record. 

NOTE 

Partitions should only be used when necessary: in certain reading, 
writing, and positioning operations, an end-of-partition can be 
mistaken for an end-of-information. 



Although the end-of-information can only be implicitly created (the 
end-of-information follows the last item written on a file), it can be 
explicitly detected with the CYP$CURRENT_ FILE _ POSITION 
procedure, described in chapter 11. 

For more information on the structure of each of the four types of 
files, refer to chapters 11 and 12. 
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Opening, Ulosmg, and totructurmg riles 11 

This chapter describes the procedures for opening, closing, and 
structuring files. 

Introduction 

CYP$OPEN_FILE 11- 

File Specification Records ................ 11- 

CYP$CLOSE_FILE 11- 

Positioning Files 

CYP$POSITION_FILE_AT_BEGINNING 11- 

r , vT3*TJnQTT , Tnisj t?tt it at wxrn ii_ 

V-^ A X If? A V-»t_/J. IXV/il mmm A. • • •• ' 1 1 I • * • -m u J. J. 

CYP$CURRENT_FILE_POSITION 11- 

CYP$LENGTH_OF_FILE 11- 

Creating File Structure 11- 

CYP$WRITE_END_OF_RECORD 11- 

nvpgwTRTTW Tmvn nv PAPTrmmv n_ 

CYP$OPERATING_SYSTEM 11- 



Upening, Closing, and Structuring Files 11 
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Introduction 

This chapter describes the procedures for opening and closing files, 
positioning files, and for creating file structure. The procedures in this 
chapter may be used with any of the four types of files supported by 
CYBIL I/O: 

Binary A binary file is treated as a stream of cells. Any 

further structure in the file is provided by the 
program that creates it. The file can be accessed 
either sequentially or randomly. Random access is 
made possible by file keys that mark cell addresses. 
(FILE _ KEY is a parameter on the binary file 
procedures described in chapter 12.) The file can be 
positioned to beginning-of-information or 
end-of-information, or to any file key. 

Record A record file is a sequence of logical records. A 

record can be read or written as a complete unit or 
in pieces (as "partial" reads or writes). A record file 
can only be accessed sequentially. It can be 
positioned to beginning-of-information, 
end-of-information, or forward or backward a 
specified number of records or partitions. 

Text A text file is essentially a file of records. Each 

record is treated as a line of characters, and each 
end-of-record as an end-of-line. A text file can only 
be accessed sequentially. It may be positioned to 
beginning-of-information or end-of-information, and 

n ** a ,-,4"k,*4. 4-~.*»4- AU ««~ U~ 4-~L1 1 J.- - Z&-J 

a.11 uuipub icai ixic i<a.ii uc bcxui/cu tu a opc^ixicu 

column or skipped a specified number of lines. 

Display A display file is a write-only text file, for printing, 

displaying at a terminal, or sending to any device 
that uses format control characters. Format control 
operations are possible, such as limiting the number 
of printed lines on a page, positioning the next line 
at a specified line number, or overprinting a line. 
There are also several ways of handling 
page-overflow. 

These four types of files are described in greater detail in chapter 12, 
along with the CYBIL I/O procedures for reading and writing files. 

The CYBIL I/O procedures and functions are not defined in the 
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Introduction 

»_/ix>iij language lxsen; tney are part 01 tne inu»/vji program 
interface. For instance, to use a CYBIL I/O procedure, a CYBIL 
program must include a *COPYC directive for the procedure 
declaration deck containing that procedure. For more information on 
referencing procedure declaration decks and on expanding CYBIL 
source programs, refer to chapter 10, How to Use CYBIL I/O. 

The procedures and functions described in this chapter are the 
following: 

CYP$OPEN_FILE 
Opens a file. 

CYP$CLOSE_FILE 
CIosss s. fils. 

CYP$POSITION_FILE_AT_BEGINNING 
Positions a file to its beginning-of-information, 

CYP$POSITION_FILE_AT_END 
Positions a file to its end-of-information. 

C YP$CURRENT_ FILE _ POSITION 
Returns the current position of a file. 

CYP$LENGTH_OF_FILE 
Returns the length of a file. 

CYP$WRITE_END_OF_RECORD 
Writes an end-of-record on a record file. 

CYP$WRITE_END_OF_PARTITION 
Writes an end-of-partition on a file. 

C YP$OPERATING_ SYSTEM 

Returns a value that identifies the operating system on which a 
program is running. 
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CYP$OPEN_FILE 

Purpose Opens a file. 

Format 



CYP$OPEN_FILE (file _ name, file .specifications, file, 
status) 



Parameters file_name: cyt$file_name; 

The name of the file to be opened. On NOS/VE, a file 
name may be up to 512 characters in length, and may be 
a file reference. 

file _ specifications: cyt$file_specifications; 

Pointer to an array of case- variant records. The array 
must be initialized before the parameter can be passed. 
The values specified in the records determine how the file 
is to be used. 

Any record left unspecified will default to the value in 
the list below. If a NIL value is specified, all of the 
records take the default values. 



file _ specification record 



Default 



close_file_disposition 

file_access 
file_character_set 
iiie _ existence 

file _ kind 
new_page_procedure 

page_format 

open_ position 

page_ length 
page_ width 



CYC$DEFAULT_FILE_ 
DISPOSITION 

CYC$READ_WRITE 

CYC$ACSII 

V/ 1 v^prNrjvv_VArv_w.LiL»_ 

FILE 

CYC$RECORD_FILE 

CYC$OMIT_PAGE_ 
PROCEDURE 

CYC$BURSTABLE_ 
FORM 

C YC$DEFAULT_ OPEN. 
POSITION 

system dependent 

system dependent 
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CYP$OPEN_FILE 



me _ contents u i u$ u in jvln u w in _ 

CONTENTS 

file.processor CYC$UNKNOWN_ 

PROCESSOR 

Following the description of CYP$OPEN_FILE is more 
information about the file specification records, the values 
that may be specified, and their defaults. For examples 
demonstrating the use of this parameter and the 
CYP$OPEN_FILE procedure in CYBIL programs, refer to 
the program examples in chapter 12, 



file: VAR of cyt$file; 

Returns a pointer that must be used on all other calls to 
the file specified by the FILE _ NAME parameter. This 
pointer is an identifier defined when the file is opened 
with this procedure. Until the file is closed (with the 
CYP$CLOSE_FILE procedure), all references to the file 
must include this identifier. In other words, this identifier 
remains defined until it is passed to the CYP$CLOSE_ 
FILE procedure. (This particular instance of the file being 
opened, with this identifier, is called the "instance of 
open" for the file.) 

Attempting to call a CYBIL I/O procedure with an altered 
or undefined pointer will have unpredictable results. 



status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file _ already _ exists 
cye$file_not_found 
cye$incorrect_ open_ request 
cye$no_memory_to_open_file 
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Remarks • The length of the file name and the characters 
included in the file name must conform to the 
requirements of the operating system; otherwise, the 
open will be aborted and abnormal status will be 
returned. 

• The values entered for the FILE _ SPECIFICATIONS 
records determine how the file is to be opened, how it 
is to be operated upon, and what is to be done with 
the file after it is closed. For more information on how 
the FILE_SPECIFICATIONS records are built, refer to 
the discussion of file specifications in this chapter, and 
to Appendix I. 

• If the capabilities of the FSP$OPEN_FILE procedure 
are needed in opening the file, refer to chapter 13 for 
a CYBIL I/O file-opening procedure that passes values 
directly to FSP$OPEN_FILE. (The FSP$OPEN_FILE 
procedure is described in the CYBIL File Management 
manual.) 
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rue »pecmcation Kecords 

The file specification records are used by the CYP$OPEN_FILE 
procedure to determine how the file is to be opened, how it is to be 
operated upon, and what is to be done with it when it is closed. Each 
is specified as a value in a record in an initialized array; the array is 



then named on the FILE_SPECIFICATIONS parameter in the call to 
CYP$OPEN_FILE. 

The example programs in chapter 12 show how file specifications are 
established in CYBIL programs. Additional information about file 
specifications is in the description of the CYP$OPEN_FILE procedure 
earlier in this chapter, and in Appendix J, which lists all the CYBIL 
I/O constants and types. 

The following are the file specification records established when a file 
is opened, and the values allowed for each. 



close _ file _ disposition 

Determines whether or not a file is detached (or deleted) after it is 
closed (type CYT$CLOSE_ FILE .DISPOSITION). 



The following values are available: 
Disposition 



Result 



CYC$UNLOAD_FILE or 
CYC$RETURN_FILE or 
CYC$DETACH_FILE 



CYC$RETAIN_FILE 



CYC$DELETE_FILE 



CYC$DEFAULT_FILE. 
DISPOSITION 



An explicit detach is performed 
when the file is closed, provided 
it has no other instances of 
open outstanding in the job. 

If the file was explicitly 
attached prior to open, the file 
remains attached. 

If the file is local, it is 
detached; if permanent, it is 
deleted. 

If the file was implicitly 
attached by CYP$OPEN_FILE 
and the file has no other 
instances of open outstanding in 
the job, the file is detached 
when it is closed. 
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The default value is CYC$DEFAULT_CLOSE_DISPOSITION. 

file_access 

Specifies the modes of access permitted on the file's data (type 
CYT$FILE_ACCESS). 

When the file is opened, the file_access record serves to validate all 
read/write requests to the file for the instance of open. The attempt to 
write to a file opened for read or to read from a file opened for write 
will be blocked and abnormal status will be returned. Enter one of 
the following values: 

CYC$READ 
Read-only access. 

CYC$WRITE 
Write-only access. 

CYC$READ_WRITE 
Read or write access. 

The default value is CYC$READ_WRITE. 

NOTE 

New files must be opened with CYC$WRITE or CYC$READ_ WRITE. 
If a file is opened as a new file (CYC$NEW_FILE on the file_ 
existence record) with CYC$READ, the attempt to open the file will 
iaii anu auiiormai status win ue returned. 

file_ existence 

Specifies whether the file is created when it is opened (type 
CYT$FILE_EXISTENCE). Enter one of the following values: 
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File Specification Records 
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CYC$OLD_FILE The file already exists, otherwise the file open 

procedure returns abnormal status. 

CYC$NEW_FILE The file is new and is created by this instance 

of open. CYP$OPEN_FILE returns abnormal 
status if this value is specified and the file 
already exists. 

CYC$NEW_OR_ If the file does not exist it will be created. 

OLD_FILE 

The default value is CYC$NEW_OR_OLD_FILE. 

fue_Kina 

Specifies the file types, and thus limits the kinds of CYBIL I/O 
procedures that may be addressed to a file (type CYT$FILE_KIND). 
The file types are the following: 

CYCSBINARY 

CYC$RECORD 

CYC$TEXT 

CYC$DISPLAY 

The default value is CYC$RECORD_FILE. These four kinds of files 
are described at the beginning of this chapter and in chapter 12. 

For example, if a file is opened as a text file, the attempt to use any 
record, binary, or display file procedure calls is prohibited and the 
status variable returned indicates CYE$INCORRECT_ OPERATION. 

file_ character _ set 

Specifies the character set for text and display files (type CYT$FILE_ 
CHARACTER_SET). 

The only character set supported by NOS/VE is CYC$ASCII (8-bit 
ASCII code), which is the default value. 
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File Specification Records 
NOTE 



The file_character„set is used only by text and display-type files. If 
this record is defined for binary or record files, it is ignored. 



file_contents 

Describes the contents of a file (type CYT$FILE_ CONTENTS). The 
use of this value is system dependent. 

The following are the available values: 

CYC$ASCII_LOG 

CYC$BINARY 

CYC$BINARY_LOG 

CYC$DATA 

CYC$FILE_BACKUP 

CYC$LEGIBLE 

CYC$LEGIBLE_DATA 

CYC$LEGIBLE_LIBRARY 

CYC$LEGIBLE_UNKNOWN 

CYC$LIST 

CYC$LIST_ UNKNOWN 

CYC$OBJECT 

C YC$OB JECT_ DATA 

CYC$OBJECT_ LIBRARY 

CYC$SCREEN 

CYC$SCREEN_FORM 

CYC$UNKNOWN_CONTENTS 
The default value is CYC$UNKNOWN_CONTENTS. 
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File Specification Records 



fda_prOCessur 



Describes the file processor (type CYT$FILE_PROCESSOR). The use 
of this value is system-dependent. 

The following are the available values: 

CYC$ADA 

CYC$APL 

CYC$ASSEMBLER 

CYC$BASIC 

CYC$C 

CYC$COBOL 

CYC$CYBIL 

CYC$DEBUGGER 

CYC$FORTRAN 

CYC$LISP 

CYC$PASCAL 

CYC$PLI 

CYC$PPU_ASSEMBLER 

CYC$PROLOG 

CYC$SCL 

CYC$SCU 

CYC$UNKNOWN_PROCESSOR 

CYC$VX 
The default value is CYC$UNKNOWN_ PROCESSOR. 
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File Specification Records 

new_page_procedure 

Specifies how page-overflow conditions are handled for display-type 
files (type CYT$NEW_PAGE_PROCEDURE). This specification builds 
a record of type CYT$PAGE_PROCEDURE_KIND. For the tag field 
of the record, specify CYC$USER_SPECIFIED_PROCEDURE, 
CYC$STANDARD_PROCEDURE, or CYC$OMIT_PAGE_ 
PROCEDURE, described below. 

CYC$USER_SPECIFIED_PROCEDURE 

Whenever a page overflow condition occurs, CYBIL I/O 
automatically calls the procedure specified by the user_procedure 
field. The user_procedure field (type CYT$USER_PAGE_ 
PROCEDURE) is a pointer to the user's page-overflow procedure. 
It passes three parameters to that procedure: 

display.file: cyt$file 

File ID established when the display file was opened. 

next_page_number: integer 
Page number of the overflow page. 

status: ost$status 

Status variable in which the status value is returned. 

CYC$STANDARD_PROCEDURE 

Whenever a page overflow condition occurs, CYBIL I/O 
automatically initiates a display-page eject and produces a standard 
title-line followed by one blank line. The title field of the new_ 

] J ;x=-_ - _j._: -r -i j_ i.i_ _ A mmn 

yagc piuccuuic icuuiu ajpci;iiic& a BLimg ui ciia.ra.ci/erb uiai tviuijj 

I/O will include in the standard title line. (For a description of the 
standard title line, refer to Page-Overflow Processing for Display 
Files in chapter 12.) 

CYC$OMIT_PAGE_PROCEDURE 
Causes a display-page eject. 

The default value is CYC$OMIT_PAGE_PROCEDURE. 

NOTE 

New_page_procedure is used only by display files. If this record is 
defined for any other type of file, it is ignored. 
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File Specification Records 
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Specifies the presence and frequency of titling in a display file with 
file contents of CYC$LIST or CYC$LIST_ UNKNOWN (type 
CYT$PAGE_FORMAT). (Titling is determined by the new_page_ 
procedure record, explained above.) 

The following values are available: 

Constant Resulting Page Format 

CYC$BURSTABLE_ Titling and display-page eject occur at 

FORM the frequency defined by the page length 

of the file. This is the recommended 
value for files that are to be listed on a 
forms printer with a page eject required 
for each page. 

CYC$NON_ Titling is separated from other data by a 

BURSTABLE_FORM triple space rather than by forcing a 

display-page eject as in 
CYC$BURSTABLE_FORM. A 
display-page eject and titling also occur 
at the frequency defined by the page 
length of the file. 

CYC$CONTINUOUS_ Titling appears once at the beginning of 

FORM the file followed by triple spacing. 

CYC$UNTITLED_FORM No titling and no display-page-eject occur 

anywhere in the file. 

NOTE 

Page_format is used only by display files. If this record is defined for 
any other type of file, it is ignored. 



open^position 

Designates where the file should be initially positioned when it is 
opened (type CYT$OPEN_CLOSE_POSITION). For an explanation of 
how this record relates to other means of specifying file position when 
the file is opened, refer to Position of File When Opened, in chapter 
10. 

The following values are available: 
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File Specification Records 

CYC$BEGINNING 

The file is opened at beginning-of-information. (CYC$BEGINNING 
takes precedence over any other file position specification, such as 
file position specified in the file reference.) 

CYC$END 

The file is opened at end-of-information. (CYC$END takes 
precedence over any other file position specification, such as file 
position specified in the file reference.) 

CYC$ASIS 

If the file has been explicitly attached, and if CYC$RETAIN_FILE 
was the close_file_disposition when the file was previously closed 
within this instance of attachment, the file is positioned to 
whatever was specified as the file position when it was closed. If 
the file was not explicitly attached, or if its close_file_disposition 
record when closed was not CYC$RETAIN_FILE, the file is 
opened at its beginning-of-information. 

CYC$DEFAULT_OPEN_POSITION 

If the open position was specified in the file reference, or was 
specified on the SCL command SET_ FILE _ ATTRIBUTES, 
CYP$OPEN_FILE uses that position when opening the file. If a 
file is opened with no file position specified at all, its open 
position is beginning-of-information. 

The default value is CYC$DEFAULT_OPEN_POSITION. 

If you want the file opened at beginning-of-information, and if the file 
was not explicitly attached (with the ATTACH_FILE command) then 
it is not necessary to specify any file position at all: 
beginning-of-information is automatically used when the file is opened 
with CYP$OPEN_FILE. If the file is explicitly attached, but no file 
position has been specified for this instance of attachment, it is 
likewise not necessary to specify any file position: 
beginning-of-information is automatically used. 

NOTE 

The FILE_POSITION parameter on the CYP$CLOSE_FILE procedure 
is also of type CYT$OPEN_CLOSE_POSITION. Under certain 
circumstances, this parameter determines the file's position at its 
close. For more information on this parameter, refer to the description 
of the CYP$CLOSE_FILE procedure later in this chapter. 
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File Specification Records 



page_length 



Specifies the number of lines on a page for display-type files (type 
CYT$PAGE_LENGTH). The page length may be 1 to 439,804,651,103 
lines. The constant CYC$PAGE_ LIMIT specifies the maximum. 

The default is a system-dependent value (60 lines on NOS/VE). 

NOTE 

Page_ length is used only by display files. If this record is defined for 
any other type of file, it is ignored. 



page_width 

Specifies the maximum length of a text line for display or text files 
(type CYT$PAGE_WIDTH). The length may be 1 to 65,535 characters. 
The following values are available: 

Constant Line Length in Characters 

CYC$NARROW_PAGE_WIDTH 80 

CYC$WIDE_PAGE_WIDTH 132 

CYC$MAX_ PAGE _ WIDTH 65535 

The default is a system-dependent value (CYC$WIDE_ PAGE _ WIDTH 
on NOS/VE). 

NOTE 

Page_width is used only by display and text files. If this record is 
defined for any other type of file, it is ignored. 
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CYP$CLOSE_FILE 

CYP$CLOSE_FILE 

Purpose Closes a file. 

Format CYP$CLOSE_FILE (file, file .position, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

file _ position : cyt$open_ close_position; 

This parameter specifies where the file is positioned 
before it is closed, but only if the file was explicitly 
attached (with the SCL command ATTACH_FILE) before 
it was opened with CYP$OPEN_FILE. If the file was not 
explicitly attached, this parameter is ignored. 

Enter one of the following values: 

CYC$BEGINNING 

File is rewound to beginning-of-information and then 
closed. 

CYC$END 

File is positioned to end-of-information and then 
closed. 

CYC$ASIS 

File is closed without positioning. 

C YC$DEFAULT_ OPEN_ POSITION 
Same as CYC$ASIS. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_ input_ request 



11-16 CYBIL Language Definition Revision F 

01/22/87 19:59:24 | 02/13/87 09:46:31 | 87/03/25 22,17.32 | 60464113 F | OPENING AND CLOSING FILES I DRAFT COPY 



CYP$CLOSE_FILE 

Remarks • The close _ file _ disposition record of the file 

specifications that were established when the file was 
opened will determine what happens to the file when 
it is closed (whether it is retained, returned, unloaded, 
or deleted). The close_file_disposition record is 
explained earlier in this chapter under File 
Specification Records. 

• The value of the FILE_POSITION parameter 
determines the file's position at its close only if the 
file was explicitly attached before it was opened. 
Furthermore, the value of this parameter is used only 
if the value of the close_file_disposition record of the 
file specifications was CYC$RETAIN_FILE, and if 
subsequent instances of open within the job specify 
CYC$ASIS on the FILE_POSITION parameter at each 
close. 

• No matter where file position is specified (on the 
open_position record of FILE .SPECIFICATIONS, in 
the file referecne, on the SET_ FILE .ATTRIBUTES 
command, or on the FILE .POSITION parameter of 
CYP$CLOSE_FILE), that specification does not 
become a permanent attribute of the file. It is in effect 
only during the instance of open or instance of 
attachment. 
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Positioning Files 

Positioning Files 

This section describes the procedures for positioning files: 
CYP$POSITION_FILE_AT_BEGINNING and CYP$POSITION_ 
FILE_AT_END. It also describes the functions for checking the 
current position of the file, CYP$CURRENT_FILE_POSITION, and 
for checking the file's length, CYP$LENGTH_OF_FILE. 

In addition, there are several ways of specifying where the file is to 
be positioned when it is opened. These are described in chapter 10, 
under Position of File at Open, and in this chapter under the 
CYP$OPEN_FILE procedure. 
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CYP$POSITION_FILE_AT_BEGINNING 
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Purpose Positions a file at its beginning-of-information. 

Format CYP$POSITION_FILE_AT_BEGINNING (file, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

Remarks To use this procedure, the file must have been opened 
with the CYP$OPEN_FILE procedure. 
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CYP$POSITION_FILE_AT_END 

CYP$POSITION_FILE .ATTEND 

Purpose Positions a file at its end-of-information. 

Format CYP$POSITION_ FILE _AT_ END (file, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_ input_ request 

Remarks To use this procedure, the file must have been opened 
with the CYP$OPEN_FILE procedure. 
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CYP$CURRENT_FILE_POSITION Function 

o i j^jluvtuliyi. _r iLJi_ruaiiiui> r uneuon 

Purpose Returns the current position of a file. 

Format CYP$CURRENT_ FILE .POSITION (file): cyt$current_ 

file_position; 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

Remarks • The following are the values that may be returned by 
this function: 

CYC$BEGINNING_OF_INFORMATION 
File is at beginning-of-information. 

CYC$MIDDLE_OF_RECORD 
File is at middle-of-record. 

CYC$END_OF_RECORD 



CYC$END_OF_PARTITION 
File is at end-of-partition. 

CYC$END_OF_INFORMATION 

File is at end-of-information. 

• Following any type of read or positioning operation, 
this function returns the current file position. 
Following most types of write operations, this function 
will return CYC$END_OF_INFORMATION. If the 
previous operation was a write to a binary file, this 
function returns CYC$MIDDLE_OF_RECORD unless 
the write extended the length of the file, in which 
case the function returns CYC$END_OF_ 
INFORMATION. 

• This function returns CYC$MIDDLE_OF_RECORD 
following a read from a binary file unless the 
NUMBER_OF_CELLS_READ parameter on the 
CYP$GET_NEXT_BINARY or CYP$GET_KEYED_ 
BINARY procedure returned a value of (zero). In 
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CYP$CURRENT_FILE POSITION Function 



this case, CYP$CURRENT_FILE_POSITION would 
return CYC$END_OF_ PARTITION or CYC$END_ 
OF_INFORMATION to indicate which file boundary 
condition was encountered. 
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CYP$LENGTH_OF_FILE Function 

CYP$LENGTH_OF_FILE Function 

Purpose Returns the length of a file. (The length is the number of 

cells in the file.) 

Format CYPSLENGTH _ OF_ FILE (file): integer; 

Format file: cyt$file; 

File identifier established when the file was opened. 
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Creating File Structure 

On NOS/VE, CYBIL I/O supports two levels of file-subdivision: records 
and partitions. 

This section describes the CYP$WRITE_END_OF_RECORD 
procedure for creating end-of-records, and the CYP$WRITE_END_ 
OF_PARTITION procedure for creating an end-of-partition. 

In addition to CYP$WRITE_END_OF_RECORD, there are other 
procedures which create end-of-records. These procedures (which are 
described in chapter 12) are the following: 

• CYP$WRITE_END_OF_LINE. 

• CYP$PUT_NEXT_RECORD and CYP$PUT_NEXT_LINE. 

• CYP$PUT_PARTIAL_RECORD with its LAST_PART_OF_ 
RECORD parameter set to TRUE. 

• CYP$PUT_PARTIAL_LINE with its LAST_PART_OF_LINE 
parameter set to TRUE. 

Although the end-of-information can only be implicitly created (it 
follows the last item physically written on a file), it can be explicitly 
detected with the CYP$CURRENT_FILE_POSITION function. 
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CYP$WRITE_END_OF_RECORD 
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Purpose Writes an end-of-record to a record file. 

Format CYP$WRITE_END_OF_RECORD (record_file, status) 

Parameters record = file: cyt$file; 

File identifier established when the file was opened, 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_output_request 

Remarks • If the last write to the file was partial, that record is 
completed; otherwise, an empty record results. 

• Attempting to use this procedure on a file not opened 
as a record-type file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

• Attempting to use this procedure on a file not opened 
with either write access or read write access will 
return CYE$INCORRECT_OUTPUT_REQUEST in the 
status variable. 
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CYPSWRITE_END_OF_PARTITION 

CYP$WRITE _END _0F_ PARTITION 

Purpose Writes an end-of-partition in a file. 

Format CYP$WRITE_END_OF_ PARTITION (file, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_output_request 

Remarks • If the last write to the specified file was a partial 

write (by means of the CYP$PUT_PARTIAL_RECORD 
or CYP$PUT_PARTIAL_LINE procedure), the record 
or line is terminated before the end-of-partition is 
written. 

• Attempting to use this procedure with a file not 
opened with either write access or read write access 
will return CYC$INCORRECT_OUTPUT_REQUEST 
in the status variable. 
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CYP$OPERATING_SYSTEM Function 
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^it-jpur-jiiJiAiuMjr^oiisiiiivi function 

Purpose Returns a value that identifies the operating system on 

which a program is running. 

Format CYP$OPERATING _ SYSTEM: cyt$system_type; 

Remarks • This function allows a program to handle any 

operating-system dependencies by first checking the 
identity of the operating system. (At present, the value 
of this function is somewhat limited, since CYBIL I/O 
has only been implemented for NOS/VE.) 

• On NOS/VE, this function returns the value 
CYC$NOSVE. 
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Reading and Writing Files 12 

This chapter describes the CYBIL I/O procedures and functions for 
reading and writing files. 

Binary Files 12- 

Binary File Structure 12- 

CYP$GET_NEXT_BINARY 12- 

CYP$GET_KEYED_BINARY 12- 

CYP$PUT_NEXT_BINARY 12- 

CYP$PUT_KEYED_BINARY 12- 

Positioning Binary Files 12- 

CYP$POSITION_BINARY_AT_KEY 

CYP$BINARY_FILE_KEY 12- 

Program Examples Using Binary Files 12- 

Record Files 12- 

Record File Structure 12- 

CYP$GET_NEXT_RECORD 12- 

CYP$GET_PARTIAL_RECORD 12- 

CYP$PUT_NEXT_RECORD 12- 

CYP$PUT_PARTIAL_RECORD 12- 

Positioning Record Files 12- 

CYP$POSITION_RECORD_FILE 12- 

Program Examples Using Record Files 12- 

Text and Display Files 12- 

Text File Structure 12- 

Display File Structure 12- 

CYP$GET_NEXT_LINE 12- 

CYP$GET_PARTIAL_LINE 12- 

CYP$PUT_NEXT_LINE 12- 

CYP$PUT_PARTIAL_LINE 12- 

CYP$WRITE_END_OF_LINE 12- 

CYP$FLUSH_LINE 12- 

CYP$TAB_FILE 12- 

CYP$SKIP_LINES 12- 

CYP$FILE_CONNECTED_TO_TERMINAL 12- 

CYP$CURRENT_COLUMN 12- 

CYP$PAGE_WIDTH 12- 

Program Examples Using Text and Display Files 12- 

Page-Overflow Processing for Display Files 12- 

CYP$START_NEW_DISPLAY_PAGE 12- 

CYP$POSITION_DISPLAY_PAGE 12- 

CYP$DISPLAY_STANDARD_TITLE 12- 



CYP$DISPLAY_PAGE_EJECT 12- 

CYP$DISPLAY_PAGE_LENGTH 12- 

CYP$CURRENT_ DISPLAY. LINE 12- 

CYP$CURRENT_PAGE_NUMBER 12- 

Program Example Using Terminal I/O 12- 
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Heading and Writing Files 12 

This chapter describes the CYBIL I/O procedures and functions for 
reading and writing files. These procedures are designed to work in 
CYBIL programs run on other operating systems, such as NOS, 
without modifications. 1 

The procedures specifically designed only for use on CYBIL for 
NOS/VE are described in chapter 13. These procedures have features 
and limitations unique to NOS/VE, and are not intended to work in 
CYBIL programs run on other systems. 

As explained in chapter 10, CYBIL I/O procedures and functions are 
not defined in the CYBIL language itself; they are part of the 
NOS/VE program interface. For more information on referencing 
procedure declaration decks and on expanding CYBIL source programs, 
refer to chapter 10, How to Use Common CYBIL I/O. 

Each of the procedures in this chapter can only be used with one of 
the four file-types: binary, record, text, or display. (Some of the 
procedures can be used with both text and display files.) For each 
file-type there is a section in this chapter describing the procedures 
and functions which pertain only to that type. In addition, each 
file-type has certain characteristics and limitations of its own. These 
are also discussed in the section on that file-type. 



1. At present, CYBIL I/O is only available on NOS/VE. 
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Binary Files 

Binary Files 

The procedures and functions described in this section are for use 
with binary files only. 

To read or write a file using CYBIL I/O, the CYBIL type of the 
parameter specifying the data to be read or written must match the 
CYBIL type of the program variable containing the data to be read or 
written. Moreover, the CYBIL I/O binary file procedures require that 
the data be specified as a pointer to a CYBIL sequence. Programs 
using the binary file procedures must therefore specify the data as a 
variable of type pointer to CYBIL sequence. This pointer is usually 
defined by using the CYBIL #SEQ function. 

For example, given the following CYBIL variable declarations: 

VAR 

data_item_1: my_data_type, 

data_item_2: "my_data_type, 

data_item_3: "array [1 .. 50] of my_data_type; 

pointers to CYBIL sequences may be defined as follows: 

#SEQ (data_item_1) 

#SEQ (data_item_2") 

#SEQ (data_item_3*) 

#SEQ (data_item_3" [5]) 



There are examples of the #SEQ function under Program Examples 
Using Binary Files later in this chapter. 

Binary File Structure 

CYBIL I/O imposes no structure on the data in a binary file. 
Therefore, any structure to be found in a binary file must be provided 
for and interpreted by the user program. For instance, the task that 
writes data on a binary-type file is responsible for determining how 
the data is to be read. It should write data-organization indicators as 
needed. As a result, a program that reads the binary file data must 
use the data conventions imposed by the program that wrote the data. 

CYBIL I/O treats the data in a binary file as a sequence of cells. 
Calls to the binary read and write procedures result in a mapping of 
cells between the file and the CYBIL program variable. 
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Binary Files 
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Binary files may be read and written in either a random or sequential 
manner. Random access of binary files is possible via the FILE _ KEY 
parameter on the binary file procedures described in this section. The 
file key may be viewed as an offset pointer that marks cell addresses 
within a binary file. The file keys identify the number of the cell 
within the file at which the data transfer begins. 

NOTE 

CYBIL I/O does not maintain a directory of file keys for binary files. 
It is the user's responsibility to create and maintain any directories 
that may be required. 



When a binary file is opened, the file key is undefined. To access the 
file using the CYP$PUT_KEYED_BINARY and CYP$GET_KEYED_ 
BINARY procedures, the file key must first be set to the current 
(open) position of the file. You can use the CYP$GET_NEXT_ 
BINARY procedure or the CYP$BINARY_ FILE _ KEY function to get 

uiiC aUUi COS tii i/iiC biiiiCiiii UiC pOS-i.Li.vf.iA. 

The sequential access procedures transfer data to or from the 
"address" or file key at which the file is currently positioned. As with 
record files, the data read or written is transferred as a block of cells 
that are mapped to the CYBIL data structure being read or written. 

Binary files may be positioned to the beginning-of-information, 
end-of-information, or to any file key within the file. Because binary 
files can be accessed randomly, positioning a binary file at the 
beginning-of-information and writing to the file does not necessarily 
mean that existing data (which follows the data being written) will be 
lost. (The opposite is true of record files, which are described later in 
this chapter). 
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The following procedures and functions may be used with binary files 
only. These procedures and functions are described in greater detail 
on the following pages. 

CYP$GET_NEXT_ BINARY 
Reads data from a binary file. 

CYP$GET_KEYED_BINARY 
Reads data from a binary file. 

CYP$PUT_NEXT_BINARY 
Writes data to a binary file. 

CYP$PUT_KEYED_BINARY 
Writes data to a binary file. 

CYP$POSITION_BINARY_AT_ KEY 

Positions a binary file to a specified file cell address. 

CYP$BINARY_FILE_KEY 

Returns the file cell address at which a binary file is currently 
positioned. 
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CYP$GET_NEXT_BINARY 

Purpose Reads data from a binary file. 

Format CYP$GET_NEXT_ BINARY (binary. file, pointer _to_ 

target, file_key, number _of_ cells = read, status) 

Parameters binary _file: cyt$file; 

File identifier established when the file was opened. 

pointer _to .target: "SEQ ( * ); 

The data structure into which data is to be read. 

file_key: VAR of integer; 

Returns the file cell address from which the read began. 



number _of_ cells _ read: VAR of integer; 

Returns the number of cells actually read. The value 
returned is normally the size of the data structure 
referenced by the POINTER. TO_ TARGET parameter. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_ input_ request 
cye$incorrect_operation 

Remarks • The data is read from the current position of the file. 

• If end-of-partition or end-of-information is detected 
during a read, the NUMBER_OF_CELLS_READ 
parameter returns only the cells read before the 
end-of-partition or end-of-information was detected. 

• Attempting to use this procedure on a file not opened 
as a binary-type file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

• Attempting to use this procedure on a file opened for 
write access will return CYE$INCORRECT_INPUT_ 
REQUEST in the status variable. 
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C YP$GET_KE YED _BINARY 

Purpose Reads data from a binary file. 

Format CYP$GET_ KEYED .BINARY (binary_file, pointer, 

to.target, file.key, number _of_ cells _ read, status) 

Parameters binary _file: cyt$file; 

File identifier established when the file was opened. 

pointer. to _ target: ~SEQ ( * ); 

The data structure into which data is to be read. 

file. key: integer; 

The file cell address at which the read is to begin. 

number, of. cells .read: VAR of integer; 

Returns the number of cells actually read. The value 
returned is normally the size of the data structure 
referenced by the POINTER_TO_TARGET parameter. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_ not _ open 

cy e$incorrect _ input_ reque st 

cye$incorrect_operation 

cye$key_past_eoi 

Remarks 



during a read, the NUMBER. OF_CELLS_READ 
parameter returns only the cells read before the 
end-of-partition or end-of-information was detected. 

If the FILE _ KEY parameter specifies a cell beyond 
the end-of-information, no data is read, CYP$GET_ 
KEYED_BINARY will return CYE$KEY_PAST_EOI 
in tuc status variaule, and the position of the file 
remains unchanged. 
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Attempting to use this procedure on a file not opened 
as a binary-type file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

Attempting to use this procedure on a file opened for 
write access will return CYE$INCQRRECT„INPUT_ 
REQUEST in the status variable. 
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CYP$PUT_NEXT_BINARY 

Purpose Writes data to a binary file. 

Format CYP$PUT_NEXT_ BINARY (binary_ffle, pointer_to_ 

source, file _ key, status) 

Parameters binary_file: cyt$file; 

File identifier established when the file was opened. 

pointer _ to _ source: A SEQ ( * ); 

The data to be written. 

file _ key: VAR of integer; 

Returns the file cell address at which the write started. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_output_request 
cye$incorrect_operation 

Remarks • The data is written to the current position of the file. 

• The end-of-information for a binary file follows the 
last physical cell written to the file. Thus, the file can 
be written, repositioned backwards, and written again 
without affecting the end-of-information. 

• The size of the data block written to a binary file is 
determined by the POINTER_TO_SOURCE 
parameter, CYBIL I/O does not "erform an v blocking 
of data. Thus, writing varying length blocks of data at 
random file addresses can cause previously written 
data blocks to be partially or fully overwritten. 

• Attempting to use this procedure on a file not opened 
as a binary-type file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

• Attempting to use this procedure on a file not opened 
for write access or read write access will return 
CYE$INCORRECT_OUTPUT_REQUEST in the status 
variable. 
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CYP$PUT_KEYED_BINARY 



uir^ru i_jvjiiJ!jU - .rsii'SArvi 



Purpose Writes data to a binary file 

Format 



CYP$PUT_ KEYED .BINARY (binary.file, pointer, 
to .source, file _ key, status) 

Parameters binary _file: cyt$file; 

File identifier established when the file was opened. 

pointer, to .source: *SEQ ( * ); 
The data to be written. 

file.key: integer; 

111c uit ten auuicas cic wiuwi biic wine ao wj t^t;gjj.i. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

cye$incorrect_output_request 
cye$incorrect_operation 

Remarks • The size of the data block written to a binary file is 
determined by the POINTER_TO_SOURCE 
parameter. CYBIL I/O does not perform any blocking 
of data. Thus, writing varying length blocks of data at 
random file addresses can cause previously written 
data blocks to be partially or fully overwritten. 

• Attempting to use this procedure on a file not opened 
as a binary-type file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

• Attempting to use this procedure on a file not opened 
for write access or read write access will return 
CYE$INCORRECT_OUTPUT_REQUEST in the status 
variable. 
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Binary File Positioning 

Binary files can be positioned to beginning or end-of-information (with 
the CYP$POSITION_FILE_AT_BEGINNING and CYP$POSITION_ 
FILE_AT_END procedures described in chapter 11). They can also be 
positioned to any random file address within the bounds of the file. 
This is done with CYP$POSITION_BINARY_AT_KEY and 
CYP$BINARY_FILE_KEY, which are described on the following 
pages. 
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CYP$POSITION_BINARY_AT_KEY 

Purpose Positions a binary file to a specified file cell address. 

Format CYP$POSITION_ BINARY. AT_ KEY (binary _file, 

file _ key, status) 

Parameters binary _file: eyt$file; 

File identifier established when the file was opened, 

file_key: integer; 

The file cell address to which the file is to be positioned. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_operation 
cye$key_past_eoi 

Remarks • If the FILE _ KEY parameter specifies a cell beyond 
the end-of-information, CYP$GET_KEYED_BINARY 
will return CYE$KEY_PAST_EOI in the status 
variable and the position of the file remains 
unchanged. 

• Attempting to use this procedure on a file not opened 
as a binary-type file will return CYE$INCORRECT_ 
OPERATION in the status variable. 
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CYP$BINARY_FILE_KEY Function 

Purpose Returns the file cell address at which a binary file is 

currently positioned. 

Format CYP$BINARY_ FILE _ KEY (binary_file): integer; 

Parameters binary_file: cyt$file; 

File identifier established when the file was opened. 

Remarks • If this function is immediately preceeded by a get or 
put procedure call, the value returned points to the 
last cell transferred + 1. If this call is immediately 
preceeded by a CYP$POSITION_BINARY_AT_KEY 
call, the value returned is the file cell address to 
which the file was positioned. 

• Attempting to use this function on a file not opened as 
a binary-type file will return a meaningless result. 
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Program Examples Using Binary Files 

This section contains CYBIL programs which employ binary file 
procedures. 

These programs perform random access on binary files. In the first 
example, a library of text modules is created from a text file. The 
modules on the source (text) file are represented as a list of lines 
whose first line contains the module name only. The module is 
terminated by an end-of-block, end-of-partition, or an 
end-of-information. 

The second example extracts one of the modules from this library and 
copies it to a file whose name is that of the module. 

Example 1: Create Text Library 

MODULE create_text_library; 

*copyc cyp$open file 

•copyc cyp$get_next_binary 

*copyc cyp$get_next_line 

*copyc cyp$wr i te_end_of _part i t i on 

•copyc cyp$current_f i leposition 

•copyc cyp$put_next_binary 

•copyc cyp$c 1 ose_f f 1 e 

•copyc cyp$position_f i leatbeginning 

•copyc cyp$put_keyed_binary 



TYPE 

directorydescriptor = record 

key: integer, 

length: integer, 
recend, 

directory_entry = record 

name: string (7), 

length: integer, 

key: integer, 
recend; 

CONST 

source_name = 'SOURCE', 
lib_name = 'LIBRARY', 
directory name = 'SCRATCH'; 
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PROGRAM create; 



VAR 

source_fi le_specs: [STATIC] array [1 ..4] of 

cy t $f i 1 e_spec i f i cat i on : = [ [ cyc$f i 1 e_access , 

cyc$pead], [cyc$fi1e_kind, cyc$text file], 

[cyc$f i l e_exi stence , cyc$ol d_f i 1 e] , 

[ cyc$open_pos i t i on , cyc$beg inning]], 
directory filespecs: [STATIC] array [1 ..3] of 

cyt$file_specification := [[cyc$f i le_kind, 

cyc$b inaryfile], [ cyc$open pos i t i on , 

cyc$beg i nn i ng ] , [ cyc$c 1 ose_f i 1 e_d i spos 1 1 i on , 

cyc$return_f i le]], 
library filespecs: [STATIC] array [1 ..3] of 

cyt$file_specification := [[cyc$fi le_access, 

cyc$write], [cyc$f i le_kind, cyc$binary_f i le], 

[ cyc$open_pos i t i on , cyc$beg i nn i ng ] ] , 
source file: cyt$file, 
libraryf i le: cyt$file, 
directory file: cyt$file, 
directory: directorydescriptor , 
current module: directoryentry, 
line: string (256), 
linelength: integer, 
module_ index: integer, 
firstkey: integer, 
dummykey : i nt eger , 
cells_read: integer, 
readstatus: ost$status, 
write_status: ost$status, 

c+ai-nc- nc+tcf atnc- 

PROCEDURE copy_a_module (VAR module_status: ost$status); 

VAR 
copy_status: ost$status, 
get_status: ost$status, 
put_status: ost$status; 



PROCEDURE copy_the_module_text (VAR local_status: 
ost$status) ; 
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VAR 
get_status: ost$status, 
put_status: ost$status; 

1 oca l_st at us. normal := TRUE; 

/copy_text_loop/ 
WHILE TRUE DO 

cyp$get_next_line (source_f i le, line, line_1ength, 

get_status) ; 
IF NOT get_st at us. normal THEN 
EXIT /copy_text_loop/; 

I FEND; 

CASE cyp$current_fi Imposition (source_f i le) OF 
= cyc$end_of_information, cyc$end_of_partition, 
cyc$end_of_block = 
ELSE 

current_module. length := current_module. length + 1; 
cyp$put next binary ( libraryfi le, #SEQ (linelength) , 

dummykey, put_status); 
IF putstatus. normal THEN 
cyp$put_next_binary (libraryfile, #SEQ (line (1, 
1 i ne_ 1 engt h ) ) , dummy_key , put_st at us ) ; 
IFEND; 
IF NOT put_st at us. normal THEN 

EXIT /copy_text_loop/; 
IFEND ; 
CASEND; 
WH I LE ND /copy_t ext _ 1 OOP/ ; 

1 oca l_st at us. normal := get _st at us. normal AND 
put _st at us. normal ; 

PROCEND copy_the_module_text ; 

/copy_modu 1 e_ 1 oop/ 
WHILE TRUE DO 

cyp$get_next_line (source_file, line, line_length, 

get_status); 
IF NOT get_status. normal THEN 

EXIT /copymodule loop/; 
IFEND; 
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CASE cyp$current_file position (source_f i le) OF 
= cyc$end_of_information, cyc$end_of_partition, 
cyc$end_of block = EXIT /copy_module_loop/; 
ELSE 

directory. length : = directory. length + 1; 
current_module.name := line (1, line_length); 
cur rentmodule. length := 1; 
cyp$put_next_binary (libraryfi le, 

#SEQ (current_module.name), currentmodule.key, 
putstatus); 
IF NOT put_st at us. normal THEN 

EXIT /copy_module_loop/; 
IFEND; 

copythe modulejtext (copy_status) ; 
IF NOT copy_st at us. normal THEN 

EXIT /copy_module_loop/; 
IFEND; 

cyp$put_next_binary (directoryf i le, 

#SEQ (current_module), dummy key, put_status); 
IF NOT put_status. normal THEN 

EXIT /copy_module_loop/; 
IFEND; 
CASEND; 
WHILEND /copymoduleloop/; 
module_st at us. normal .= copyst at us. normal AND 
putst at us. normal AND get_st at us. normal ; 

PROCEND copyamodu 1 e ; 

PROCEDURE copy_directory_to_library (VAR local_status: 
ost$status); 

VAR 
module index: integer, 
read_status: ost$status, 
write_status: ost$status; 

cyp$get_next_binary (directoryfi le, #SEQ (current_module), 

dummykey , ce 1 1 s_r ead , r ead_st at us ) ; 
IF read_st at us. normal THEN 

cyp$put_next_binary (libraryfile, #SEQ (current_module), 
directory. key, write_status) ; 

IF write status. normal THEN 
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/readjoop/ 

FOR module_index := 2 TO directory. length DO 
cyp$get_next_binary (directory fi le, 

#SEQ (currentmodule), dummykey, cens_read, 
readstatus) ; 
IF NOT read_stat us. normal THEN 

EXIT /readjoop/; 
I FEND; 
cyp$put_next_binary (library fi le, 

#SEQ (current_module), dummykey, write_status) ; 
IF NOT write_st at us. normal THEN 

EXIT /readjoop/; 
IFEND; 
FOREND /readjoop/; 

IF read_st at us. normal AND write_status. normal THEN 
cyp$put_keyed_binary (library file, #SEQ (directory), 
first key, writestatus); 
IFEND; 
IFEND; 
I FEND, - 

localstatus. normal := read_st at us. normal AND 
write status. normal ; 



PROCEND copy_di rectory tol ibrary; 



cyp$open_f i 1 e ( sourcename , " sourcej 1 i 1 e_specs , sourcej i 1 e , 

status) ; 
IF status. normal THEN 
cyp$openJM le (directoryname, "directory fi le_specs, 

directoryfile, status); 
IF status. normal THEN 
cyp$open f i 1 e ( 1 i b_name , * 1 i brary f i 1 e_specs , 
library file, status); 

IFEND; 
IFEND; 

IF status. normal THEN 

/mainprogram/ 
BEGIN 
{*} 
{ reserve space for a directory 
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directory. length := 0; 

cyp$put_next_binary (libraryfile, #SEQ (directory), 

first_key, write_status) ; 
IF write_status. normal THEN 
copy_a_module (read status) ; 
cyp$close_file (source_f i le, cyc$end, status); 
IF ((readst at us. normal) AND (directory. length > 0)) 
THEN 

cyp$pos i t i onf i 1 e_at_begi nn i ng ( di r ectoryf i 1 e , 
status); 
IF NOT status. normal THEN 

EXIT /mainprogram/; 
IFEND; 

copydi rectory tolibrary (status) ; 

IFEND; 
IFEND; 

END /mainprogram/; 

IFEND; 

cyp$close_f i le (directoryf i le, cyc$asis, status); 

cyp$close_f 1 le (library file, cyc$beginning, status); 

PROCEND create; 

MODEND create_text_.library ; 
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example z: extract r rom lext uorary 

This example extracts one of the modules from the library created in 
the first example and copies it to a file whose name is that of the 
module. 

MODULE extract_fromtext_ library; 

•copyc cyp$open_fi le 
•copyc cyp$close_f i le 
•copyc cyp$get_next_binary 
•copyc cyp$get_keyed_binary 
•copyc cyp$posi t ion bi nary at key 
•copyc cyp$put_keyed_binary 
•copyc cyp$put_next_line 
•copyc cyp$current_fi le_position 

TYPE 

directory_descMptor = record 
key: integer, 
length: integer, 
recend, 

directoryentry = record 

name: string (7), 

length: integer, 

key: integer, 
recend; 

CONST 

lib_name = 'LIBRARY'; 

CONST 
name_of_module = 'TEXTMOD'; 



PROGRAM extract; 

VAR 

library_file_specs: [STATIC] array [1 ..4] of 
cyt$file_specification := [[cyc$f i le_kind, 
cyc$binary_fi le], [cyc$open_position, cyc$beginning], 
[cyc$f i le_existence, cyc$old_f ile], [cyc$f i le_access, 
cyc$read]], 
output_file_specs: [STATIC] array [1 ..3] of 

cyt$f ile_specif ication := [[cyc$f i le_access, cyc$write], 
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[cyc$file_kind, cyc$text_f i le], [cyc$open_position, 

cyc$beginning]], 
libraryfile: cyt$file, 
out_file: cyt$f1le, 
directory: directorydescriptor , 
currentmodule: directoryentry, 
line.- string (256), 
line length: integer, 
modu 1 e_f ound : boolean, 
dummykey : i nt eger , 
cellsread: integer, 
status: ost$status; 

PROCEDURE search formodule (librarydirectory: 
di rectorydescr i ptor ; 
VAR module i si ndi rectory: boolean; 
VAR searchstatus: ost$status); 



modu le_ index 


: integer 




module. 


isind 


rectory : 


= FALSE; 


search 


status. 


normal := 


TRUE; 



cyp$posi t i onb i nary atjcey ( 1 i braryf i 1 e , 

library directory. key, search status) ; 
IF NOT searchst at us. normal THEN 

RETURN; { > 

IFEND; 

/search di rectory/ 

FOR module_index := 1 TO librarydirectory. length DO 
cyp$get_next_binary (library file, #SEQ (current module), 

dummy key, cellsread, searchstatus); 
IF NOT searchstatus. normal THEN 

RETURN; { > 

IFEND; 

IF cur rentmodule. name = name_of module THEN 
modu le_is_in di rectory := TRUE; 
EXIT /search directory/; 
IFEND; 
FOREND /searchdi rectory/; 

PROCEND search for module; 
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PROCEDURE copy themodulejext (VAR copy_status: ost$status); 

/modulejoop/ 
WHILE cur rent_modu 1 e . length > 1 DO 

cyp$get_next_binary (library fi le, #SEQ (!1ne_length), 

dummy key, cellsread, copystatus); 
IF NOT copy_st at us. normal THEN 

EXIT /modulejoop/; 
IFEND; 
cyp$get_next_b1nary (libraryfi le, #SEQ (line (1, 

linelength)), dummy key, cells_read, copy_status) ; 
IF NOT copystatus. normal THEN 

EXIT /modulejoop/; 

IFEND: 

cyp$put_next 1 i ne (outjile, line (1, linejength), 

copy_status) ; 
IF NOT copy status. normal THEN 

EXIT /modulejoop/; 
IFEND; 

cur rentjnodule. length := currentjnodule. length - 1; 
WHILEND /modulejoop/; 
PROCEND copyjhejnodulejext ; 

cyp$open file (lib_name, 'library file_specs, library file, 

status); 
IF NOT st at us. normal THEN 

RETURN; { > 

IFEND; 

cyp$get_next_binary (library fi le, #SEQ (directory), 

dummykey, cells_read, status); 
IF NOT stat us. normal THEN 

RETURN; { > 

IFEND; 

IF directory. length = THEN 

RETURN; { > 

IFEND; 

search formodu 1 e (directory, modu 1 ejound , status); 

IF status. normal AND modulejound THEN 
cyp$open_f i le ( nameofjnodu 1 e , "output fi lespecs, 

outjile, status); 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 
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cyp$get_keyed_blnary ( 1 ibraryf i le, 

#SEQ ( cur rentjnodule. name), cur rentjnodule. key, 

cells_read, status); 
IF NOT st at us. normal THEN 

RETURN; { > 

IFEND; 

cyp$put jiext l i ne (out_file, cur rentjnodule. name, status); 

IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

copyjjhe module_text (status); 
IFEND; 

cyp$close f i le (library _fi le, cyc$beg inning, status); 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$close _fi le (out_file, cyc$beginning, status); 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

PROCEND extract; 

MODEND extractJ=rom text library; 
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Kecord Files 

The procedures and functions described in this section are for use 
with record files only. To use other types of files with CYBIL I/O, 
refer to the appropriate section of this chapter. 

The data transfer procedures for record files (like any 
programmer-defined procedures in CYBIL) must have parameters of a 
specific CYBIL type. To transfer data to or from a record file, the 
CYBIL type of the parameter that specifies the data to be read or 
written must match the CYBIL type of the program variable that 
contains the data to be read or written. The CYBIL I/O procedures 
that read and write on record files require that the data be specified 
as a pointer to a CYBIL sequence. Programs using the record file 
procedures must therefore soeeifv the data as a variahlfi nf tvrw» 
pointer to CYBIL sequence. This pointer is usually defined by using 
the CYBIL #SEQ function. 

For example, given the following CYBIL variable declarations: 

VAR 
dat a_ i t em_ 1 : my_dat a_t ype , 
data_item_2: "my_data_type, 
data_item_3: 'array [1 .. 50] of my_data_type; 

the pointers to CYBIL sequences may be defined as follows: 

#SEQ (data_item_D 

#SEQ (data_item_2~) 

#SEQ (data_item_3") 

#SEQ (data_item_3* [5]) 

For examples using the CYBIL #SEQ function to pass data to or from 
the record-file read/write procedures, refer to Program Examples Using 
Record Files later in this chapter. 

Data is read from or written to record type files as full or partial 
records. These records are not to be confused with the CYBIL record 

type. 

Record File Structure 

In record files, data exists as a sequence of logical records each of 
which is terminated with an end-of-record. CYBIL I/O allows the 
reading and writing of both full and partial records. That is, a record 
may be transferred as the result of a single read or write operation, 
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or a record may be transferred as the result of several partial read or 
write operations. Record file reads and writes map the data to a 
CYBIL data structure. For example, a CYBIL array may be written 
as a record or partial record. The address and size of the data 
structure are passed to CYBIL I/O as a CYBIL sequence pointer. 
CYBIL I/O uses this information to write a record that exactly 
corresponds byte for byte with the way the data is stored in the 
CYBIL data structure. 

CYBIL I/O supports only sequential access of record files. Data 
appears on such files in the order in which it was written, and can 
only be read in the same order. 

Record files may be positioned to the beginning-of-information or 
end-of-information. In addition, record files may be positioned forward 
or backward a user-specified number of records or partitions. 
Positioning a record file backwards and then writing to the file means 
that any data following the data just written to the file is lost. 

The end-of-information always immediately follows the last data 
written to the file. 
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ine ionowing proceaures ana iuncuons may De usea wiin recora nies 
only. These procedures and functions are described in greater detail 
on the following pages. 

CYP$GET_NEXT_RECORD 

Reads the next record from a record file. 

CYP$GET_PARTIAL_RECORD 

Reads a portion of a record from a record file. 

CYP$PUT_NEXT_RECORD 
Writes a record on a record file. 

CYP$PUT_PARTIAL_RECORD 
Writes a partial record on a record file. 

CYP$POSITION_RECORD_FILE 
Allows a record file to be repositioned. 
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CYP$GET_NEXT_RECORD 

Purpose Reads the next record from a record file. 

Format CYP$GET_NEXT_RECORD (record _file, pointer_to_ 

target, number _of_ cells _ read, status) 

Parameters record _file: cyt$file; 

File identifier established when the file was opened. 

pointer_to_target: "SEQ ( * ); 

The data structure into which data is to be read. 

number_of_cells_read: VAR of integer; 
Returns the number of cells actually read. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_ input_ request 
cye$incorrect_ operation 

Remarks • If the current file position is not at the beginning of a 
record, the file is positioned forward to the beginning 
of the next record or partition before the read begins. 

• CYBIL I/O reads data from the file until it encounters 
the end-of-record or the end of the data structure 

<nu.«i'fl/,J U-r ±U#> r>nTTVTT'17T> T>n rrADnUT i. 

k3£*i*i*xxxwu *J>j VLM.%* ± Will XUlh_ J. Vy_ liTIlUlJ A pal CL111C LCI . 

The NUMBER_OF_CELLS_READ parameter will 
return the number of data cells actually read into the 
data structure specified by POINTER_TO_TARGET. 

• If the read terminates because the end-of-record was 
encountered, the CYP$CURRENT_FILE_POSITION 
function will return CYC$END_OF_RECORD. If the 
read terminates because CYBIL I/O encountered the 
end of the POINTER_TO_TARGET data structure, the 
CYP$CURRENT_FILE_POSTIION function will return 
CYC$MIDDLE_OF_RECORD. To read the remainder 
of the record, the program must issue CYP$GET_ 
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FILE_POSITION function returns a value of 
CYC$END_OF_RECORD. (The CYP$CURRENT_ 
FILE_POSITION function is described in chapter 11.) 

• If an end-of-partition is encountered, no data is read, 
the NUMBER_OF_CELLS_READ parameter returns 
a value of (zero), and the CYP$CURRENT_FILE_ 
POSITION function will return a value of CYC$END_ 
OF_PARTITION. 

• If an end-of-information is encountered, no data is 
read, the NUMBER. OF_CELLS_ READ parameter 
returns a value of (zero), and the CYP$CURRENT_ 
FILE_POSITION function will return a value of 
CYC$END_OF_INFORMATION. 

• Attempting to use this procedure on a file not opened 
as a record file will return CYE$INCORRECT_ 
OPERATION in the status variable. 



write access will return CYE$INCORRECT_INPUT_ 
REQUEST in the status variable. 
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CYP$GET_PARTIAL_RECORD 

Purpose Reads a portion of a record from a record file. 

Format CYP$GET_PARTIAL_RECORD (record_file, pointer, 

to _ target, number _of_ cells _ read, last _ part _ of _ 
record, status) 

Parameters record_file: cyt$file; 

File identifier established when the file was opened. 

pointer_to_target: "SEQ ( * ); 

Specifies the data structure into which data is to be read. 

number _of_ cells _ read: VAR of integer; 
Returns the number of cells actually read. 

last_part_of_record: VAR of boolean; 

Returns a value of TRUE if the end-of-record was 
encountered, and a value of FALSE otherwise. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_input_request 
cye$incorrect_operation 

Remarks • Reading begins at the current position of the file and 
continues until the end-of-record or the end of the data 
structure specified by POINTER. TO_ TARGET is 
encountered. The NUMBER_OF_CELLS_READ 
parameter will return the number of data cells 
actually read into the data structure specified by 
POINTER_TO_TARGET. 

• If the read terminates because the end of the record 
was encountered, the CYP$CURRENT_FILE_ 
POSITION function will return CYC$END_OF_ 
RECORD. If the read terminates because the end of 
the POINTER_TO_TARGET data structure was 
encountered, the CYP$CURRENT_ FILE .POSITION 
function will return CYC$MIDDLE_OF_ RECORD. To 
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react tne remainder 01 tne record, tne program must 
issue CYP$GET_PARTIAL_RECORD calls until the 
CYP$CURRENT_FILE_POSITION function returns a 
value of CYC$END_OF_RECORD. 

If the end-of-partition is encountered, no data is read, 
the NUMBER_OF_CELLS_READ parameter returns 
a value of (zero), and the CYP$CURRENT_FILE_ 
POSITION function will return a value of CYC$END_ 
OF_PARTITION. 

If the end-of-information is encountered, no data is 
read, the NUMBER. OF_CELLS_READ parameter 
returns a value of (zero), and the CYP$CURRENT_ 
FILE_POSITION function will return a value of 
CYC$END_OF_INFORMATION. 

Attempting to use this procedure on a file not opened 
as a record file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

Attempting to use this procedure on a file opened for 
write access will return CYE$INCORRECT_INPUT_ 
REQUEST in the status variable. 
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CYP$PUT_NEXT_ RECORD 

Purpose Writes a record on a record file. 

Format CYP$PUT_NEXT_RECORD (record_file, pointer_to_ 

source, status) 

Parameters record _file: cyt$file; 

File identifier established when the file was opened. 

pointer_to_source: "SEQ ( * ); 

The data to be written. The data is written as a complete 
record. If the last write to the file was made with 
CYP$PUT_PARTIAL_RECORD, that record is completed 
before the data specified by this parameter is written as a 
new complete record. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_output_request 
cye$incorrect_ operation 

Remarks • The end-of-information on a record file immediately 
follows the data last written. Thus, if you write to a 
record file, and then position the file to its beginning 
(or perform a backward record skip) and again write 
to the file, data will be lost. 

• Attempting to use this procedure on a file not opened 
as a record file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

• Attempting to use this procedure on a file not opened 
with either write access or read write access will 
return CYE$INCORRECT_OUTPUT_REQUEST in the 
status variable. 
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Purpose Writes a partial record on a record file. 

Format CYP$PUT_PARTIAL_RECORD (record.file, pointer, 

to_source, last _ part _ of _ record, status) 

Parameters record _ file: cyt$file; 

File identifier established when the file was opened. 

pointer_to_souree: A SEQ ( * ); 
Specifies the data to be written. 

last _ part _ of _ record: boolean; 

opeciiies whether or not more data can be appended to 
the- current record. If this parameter is TRUE, the data 
specified by the POINTER_TO_SOURCE parameter is 
written to the file and the record is terminated. The next 
full or partial write to the file will begin a new record. 

If this parameter is FALSE, the data specified by the 
POINTER_TO_SOURCE parameter is written to the file 
but the record is not terminated. Additional data can be 
appended to the record if the next write to the file is 
done by the CYP$PUT_PARTIAL_RECORD procedure. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_output_request 
cye$incorrect_operation 

Remarks • The end-of-information on a record file immediately 
follows the data last written. Thus, if you write to a 
record file, and then position the file to its beginning 
(or perform a backward record skip) and again write 
to the file, data will be lost. 

• Attempting to use this procedure on a file not opened 
as a record file will return CYE$INCORRECT_ 
OPERATION in the status variable. 
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Attempting to use this procedure on a file not opened 
with either write access or read write access will 
return CYE$INCORRECT_OUTPUT_REQUEST in the 
status variable. 
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iteeorcl *ne Positioning 

On NOS/VE, record files can be subdivided into records or partitions. 
They can be positioned to either beginning or end-of-information (with 
the CYP$POSITION_FILE_AT_BEGINNING and CYP$POSITION_ 

only be performed on record files that were opened for read or read 
write access. 

Record files can also be positioned forward or backward one or more 
records or partitions with the CYP$POSITION_RECORD_FILE 
procedure, described on the following pages. 
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CYP$POSITION_RECORD_FILE 

Purpose Repositions a record file. 

Format CYP$POSITION_RECORD_FILE (record_file, 

direction, count, unit, status) 

Parameters record _file: cyt$file; 

File identifier established when the file was opened. 

direction: cyt$skip_direction; 

Specifies forward or backward positioning. Enter one of 
the following values: 

CYC$FORWARD 

CYC$BACKWARD 

count: integer; 

The number of units the file is to be positioned. 

unit: cyt$skip_unit; 

How the file is to be repositioned (by records or 
partitions). Enter one of the following values: 

CYC$RECORD 

CYC$PARTITION 

status: VAR of ost$status; 

GU-nt-„„ ,„,„4„l,l,. ;— ...U4»u iL. l-i.: _i._i :_ 
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returned. 

Conditions cye$file_not_open 

cye$incorrect_input_request 
cye$incorrect_operation 
cye$incorrect_skip_count 
cye$premature _ end_ of _ operation 

Remarks • Attempting to use this procedure on a file not opened 
as a record file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

• Attempting to use this procedure on a file opened for 
write access will return CYE$INCORRECT_INPUT_ 
REQUEST in the status variable. 
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ine position oi tne me alter a positioning operation 
depends on the positioning unit (records or partitions), 
the initial file position, the number of units positioned, 
and the positioning direction. Table 12-1 lists 
positioning results assuming that no boundary 



condition is detected befo 
exhausted. 



the positioning count is 



Table 12-1. Results of CYP$ POSIT ION_RECORD_FILE 

Result 



File position 
before the 
operation 



Positioning 
operation 



Positioning by 
records: 



cyc$beginning_of_ 
information, 
end_ of _ record, 
end_of_ partition, 



pnn r\T 



information 
middle _ of _ record 



Position forward or 
backward zero 
records. 



Position forward 
zero records. 



No movement; the file 
remains the same as 
before the positioning 
operation. 



The file is positioned to 
the end of the current 
record. 



middle_of_record 



Position backward 
zero records. 



The file is positioned to 
the end of the preceeding 



recora. 



End of record N 



End of record N 



Positioning by 
partitions: 

beginning... of _ 
information, 
end_of_ 
information 



Position forward 
one or more (M) 
records. 

Position backward 
one or more (M). 
records. 



Position forward or 
backward zero 
partitions. 



The file is positioned to 
the end of record N + M. 



The file is positioned to 
the end of record N - M. 



No movement; the file 
remains positioned the 
same as before the 
positioning operation. 



Revision F 



Reading and Writing Files 12-35 



CYP$POSITION_RECOBD_FILE 



middle_of_record, 

end_of_record, 

end_of_partition 

middle _ of _ record, 
end_of_record, 
end_of_ partition 

middle _ of _ record, 

end_of_record, 

end_of_partition 

middle _ of _ record, 
end_ of _ record, 
end_of_ partition 



Position forward 
zero partitions. 

Position backward 
zero partitions. 

Position forward 
one or more (M) 
partitions. 

Position backward 
one or more (M) 
partitions. 



The file is positioned to 
the beginning of the next 
partition. 

The file is positioned to 
the beginning of the 
current partition. 

The file is positioned to 
the beginning of partition 
(current + M +1). 

The file is positioned to 
the beginning of partition 
(current - M). 



In Table 12-1 it is assumed that no boundary conditions 
are encountered during the positioning operation. If 
CYP$POSITION_RECORD_FILE encounters a boundary 
condition before the count is exhausted, the positioning 
operation stops at the boundary and CYE$PREMATURE_ 
END_OF_OPERATION will be returned in the status 
variable. 

The following are the boundary conditions: 

• A position forward by records encounters an 
end-of-partition or end-of-information. 

• A position forward by partitions encounters 
end-of-information. 

• A position backwards by records encounters an 
end-of-partition or beginning-of-information. 

• A position backwards by partitions encounters 
beginning-of-information. 
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iTogram Jixampie using necora rues 

The following example illustrates the use of record file procedures. 
The input file is assumed to contain several kinds of logical records. 
An id-record identifies the record following it as either an employee 
record or a vendor record. A vendor record is followed by one or more 
product records. This program produces a list of vendor names and 
the names of the products supplied by each vendor. 

Example 1: Extract Information From Records 

MODULE 1 i st_vendor_and_product s ; 

•copyc cyp$open_fi le 
•copyc cyp$close_f i le 
•copyc cyp$get_next_record 
*copyc cyp$put nextline 
•copyc cyp$put_partial_line 
copyc cyp$pcs t ^ ion_rscoru_i i is 
•copyc cyp$tab_file 
•copyc cyp$current_fi le_position 



PROGRAM list_vendor_and_products; 

CONST 

inname = 'EMPDB', 
out_name = 'EMPLIST'; 

TYPE 

ful l_name = record 

first: string (10), 

initial: char, 

last: string (15), 
recend , 

employeeentry = record 

number : . . 999999 , 

name: full_name, 

departmentnumber : .. 9999, 

department name: string (20), 
recend, 

wendor_entry = record 
number: .. 99999999, 
name: string (30), 
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street_address: string (30), 
citystate: string (30), 
zip code: . . 99999, 
numberofproducts: integer, 
recend, 

product_entry = record 

name: string (20), 

product_number : string (10), 
recend , 

entryid = (employee id, vendorid); 

VAR 

infile: cyt$file, 
• out_file: cyt$file, 

i n_f i 1 e_specs : cy t $f i 1 espec i f i cat i ons , 

outf i lespecs: cyt$f i le_specifi cat ions, 

cells_read: integer, 

vendor : vendorent ry , 

product: product entry, 

record_id: entryid, 

i: integer, 

status: ost$status; 

PUSH in_file_specs: [1 .. 4]; 
in _fl le_specs* [1]. selector := cyc$fi le_kind; 
infi le_specs" [1].f i le_kind := cyc$record_file; 
infi lespecs* [2]. selector : = cyc$f i 1 e_access ; 
infi le_specs* [2].f i leaccess := cyc$read; 



in file_specs* [3].f i le_existence := cyc$old_f ile; 
in_file_specs* [4]. selector := cyc$open_position; 
infile specs* [4].open_position := cyc$beg inning; 

PUSH out_file_specs: [1 .. 3]; 

out_file_specs* [1]. selector := cyc$fi le_kind; 

out_file_specs" [1] .f i le_kind := cyc$text_fi le; 

outf i le_specs* [2]. selector := cyc$fi leaccess; 

out_f i le_specs* [2] .f ile_access := cyc$write; 

out_file_specs" [3]. selector := cyc$open_position; 

outf i lespecs" [3] .openposition := cyc$beg inning; 



cyp$open_file (inname, inf i le specs, infile, status); 
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IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$open_file (outjiame, out_f i le_specs, out_file, status); 
IF NOT st at us. normal THEN 

RETURN; { > 

IFEND; 

/mainloop/ 
WHILE status. normal DO 

cyp$get_next_record (infile, #SEQ (record_id), 

cells_read, status); 
IF NOT stat us. normal THEN 

EXIT /mainloop/; 
IFEND; 

CASE cyp$current_f ileposition (infile) OF 
= cyc$end_of_partition, cyc$end_of_block = 

CYCLE /ma1n_loop/; 
= cyc$end_of_information = 

EXIT /main loop/; 
= cyc$middle_of record = 
cyp$put_next_line (out_file, 'ERROR reading input file', 

status) ; 
EXIT /mainloop/; 
= cyc$end_of_record = 
CASE record_id OF 
= employeeid = 
cyp$position record_f i le (infile, cyc$forward, 1, 

cyc$record, status); 
IF NOT st at us. normal THEN 

EXIT /main_loop/; 
IFEND; 
= vendor_id = 
cyp$get_next_record (in file, #SEQ (vendor), 

cells_read, status); 
IF NOT stat us. normal THEN 

EXIT /main loop/; 
IFEND; 

IF cyp$current_f i le_position (infile) = 
cyc$end_of_record THEN 

cyp$put_next_line (out_file, vendor. name, 
status) ; 
IF NOT stat us. normal THEN 

EXIT /mainloop/; 
IFEND; 
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FOR i : = 1 TO vendor . number_of_product s DO 
cyp$get_next_record (infile, #SEQ (product), 

cells_read, status); 
IF cyp$current_fi Imposition (in file) <> 
cyc$end_of_record THEN 

cyp$put_next_line (out file, 'ERROR reading 
input file', status); 
EXIT /mainloop/; 
ELSEIF (NOT status. normal ) OR (cells_read <> 
#SIZE (product)) THEN 
EXIT /main loop/; 
IFEND; 

cyp$tab_file (out file, 10, status); 
IF NOT status. normal THEN 

EXIT /main loop/; 
IFEND; 
cyp$put_partial_line (out_file, product . name , 

TRUE, status); 
IF NOT status. normal THEN 

EXIT /mainloop/; 
IFEND; 
FOREND; 
ELSE 
cyp$put_next_line (outfile, 'ERROR reading input 

file', status); 
EXIT /mainloop/; 
IFEND; 
CASEND; 
CASEND; 



cyp$close file (infile, cyc$beg inning, status); 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$close_file (out_file, cyc$beg inning, status); 

IF NOT st at us. normal THEN 

RETURN; { > 

IFEND; 

PROCEND 1 ist_vendor and_products; 

MODEND 1 ist_vendor_and_productS; 
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Heading and Writing Text and .Display riles 

The procedures and functions described in this section are for use 
with text and display-type files only (they apply to both). 

Data is transferred to and from text files and dis T1 la v files as lines or 
partial lines. Internally, these lines are represented as CYBIL strings 
of characters. Externally (on the file), lines may be represented in 
8-bit ASCII. 

The external character set is specified on the FILE_SPECIFICATIONS 
parameter of the CYP$OPEN_FILE procedure when the file is 
opened. Data transfers on text or display files may involve a 
translation between character sets (unlike binary and record file 
transfers, in which the file data is not modified). 

The maximum line-length written to text or display files, and the 
page size for display files, are specified with the FILE_ 
SPECIFICATIONS parameter on the CYP$OPEN_FILE procedure. 

Text File Structure 

A text file, which is a variation of a record file, is assumed to contain 
character data. Since character data is generally conceived of as lines, 
text-file records are treated as lines and the end-of-record for text files 
as end-of-line. 

The basic entity on a text file is a line which can be transferred to or 
from the file in whole or in part. In addition, it is possible to tab to a 
specified column in an output line and skip a specified number of 
lines. Text files may be positioned to the beginning-of-information or 
to the end-of-information. 

Data is passed to and from the text file procedures as CYBIL strings 
rather than as CYBIL sequence pointers. Like record files, text files 
can only be accessed sequentially. 

Display File Structure 

A display file is a special form of write-only text file. Display files 
should be used when the file is to be printed, or routed to any device 
which uses format control characters. Format control characters are 
automatically prefixed to each line written to display-type files. 
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Display files have additional facilities for vertical format control 
(described on the following pages). It is possible to limit the number 
of printed lines on a page, insert a given number of empty lines, 
overprint lines, or position the next line at a specified line number or 
at the top of the next display page. Several functions are provided to 
interrogate certain items of display page information for display files. 

Display files may only be written. If it is necessary to read a file 
which was written as a display file, the file should be accessed as a 
text file. 

With each display file, you may associate a procedure to be called 
when a page overflow condition occurs for that file. The procedure 
may be one of your own or a special internal CYBIL I/O procedure 
that produces a standard title line. (A page-overflow procedure of your 
own is specified on the FILE .SPECIFICATIONS parameter of 
CYP$OPEN_FILE. For more information on page-overflow handling, 
refer to Page-Overflow Processing for Display Files later in this 
chapter.) 
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Display File Structure 
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lxie loiiuwiiig proceaures ana l unctions may De usea wnn text ana 
display files only. These procedures and functions are described in 
greater detail on the following pages. 

CYP$GET_NEXT_LINE 

Reads the next complete line from a test or display file. 

CYP$GET_PARTIAL_LINE 

Reads a character string from a text or display file. 

CYP$PUT_NEXT_LINE 

Writes a string of characters to a text or display file. 

CYP$PUT_PARTIAL_LINE 

Writes a string of characters to a text or display file. 

C YP$WRITE _ END_ OF_ LINE 

Writes an end-of-iine to a text or display file. 

CYP$FLUSH_LINE 

Flushes the line buffer for a text or display file. 

CYP$TAB_FILE 

Positions a text or display file to a s r >ecified column or THisition 
within a line. 

CYP$SKIP_ LINES 

Writes one or more blank lines to a text or display file. 

CYP$FILE_CONNECTED_TO_TERMINAL 

Determines whether or not a text or display file is connected to a 
terminal. 

C YP$CURRENT_ COLUMN 

Returns the current column within the current line of a text or 

display file. 

CYP$PAGE_WIDTH 

Returns the page width associated with a text or display file. 
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CYP$GET_NEXT_LINE 

Purpose Reads the next complete line from a text or display file. 

Format CYP$GET_NEXT_LINE (file, line, number _of_ 

characters _ read, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

line: VAR of string ( * < = cyc$max_page_width); 

The CYBIL string into which the line was read. If the 
line from the file is too long to fit into this string, the 
line is truncated by skipping to the end of the line after 
the transfer is complete. 

number_of_characters_read: VAR of integer; 

Returns the number of characters transferred into the 
string specified by the LINE parameter. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_ input_ request 
cye$incorrect_ operation 

Remarks • If the previous transfer was partial, a skip to the end 
of that line is performed prior to this read. 

• A line containing zero characters is returned as an 
empty string (the NUMBER. OF_ CHARACTERS. 









no characters is one in which a carriage return was 
entered in the first position of the line, or is any 
empty line that was written via a call to 
CYP$WRITE_END_OF_LINE. 

• Attempting to use this procedure on a file not opened 
as a text or display-type file will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 



12-44 CYBIL Language Definition Revision F 

| 01/22/87 19:59:24 | 02/13/87 09:46:31 | 87/03/25 22.17.32 | 60464113 F | READING AND WRITING FILES | DRAFT COPY 



CYP$GET_NEXT_LINE 
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attempting to use txiis procedure on a. iaie opened lor 
write access will return CYE$INCORRECT_INPUT_ 
REQUEST in the status variable. 
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C YP$GET_ PARTIAL _LINE 

Purpose Reads a character string from a text or display file. 

Format CYP$GET_ PARTIAL. LINE (file, partial_line, 

number _ of _ characters _ read, last _ part _ of _ line, 
status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

partial_line: VAR of string ( * < = cyc$max_page_ 
width); 

The CYBIL string into which the character string is read. 

number _of_ characters _ read: VAR of integer; 

Returns the number of characters transferred into the 
string specified by the partial_line parameter. 

last_part_of_Iine: VAR of boolean; 

Returns a value of TRUE if the end of the line was 
encountered, and a value of FALSE otherwise. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_input_request 
cye$incorrect_operation 

Remarks 



A line containing zero characters is returned as an 
empty string (the NUMBER_OF_ CHARACTERS. 
READ parameter returns a value of zero). A line with 
no characters is one in which a carriage return was 
entered in the first position of the line, or is any 
empty line that was written via a call to 
CYP$WRITE_END_OF_LINE. 

Attempting to use this procedure on a file not opened 
as a text or display-type file will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 
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CYP$GET_PARTIAL_LINE 

• Attempting to use this procedure on a file opened for 
write access will return CYE$INCORRECT_INPUT_ 
REQUEST in the status variable. 



Revision F Reading and Writing Files 12-47 



CYP$PUT_NEXT_LINE 

CYP$PUT_NEXT_LINE 

Purpose Writes a string of characters to a text or display file. 

Format CYP$PUT_NEXT_LINE (file, line, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

line: string ( * < = cyc$max_page_width); 

The string of characters to be written as a complete line. 
If the last write to the file was a partial line, that line is 
first completed, and then the characters specified by this 
parameter are written. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_output_ request 
cye$incorrect_ operation 

Remarks • If the length of the character string exceeds the page 
width, the line will be truncated. 

• For a display file, format control characters are 
automatically prefixed to the new line. (The format 
control characters that are used depend on what kind 
of write operation preceded this call to CYP$PUT_ 
NEXT_LINE.) In addition, if displaying the line 
causes the display page length to be exceeded, the 
page overflow mechanism is executed. 

• Attempting to use this procedure on a file not opened 
as a text-type or display-type file will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 

• Attempting to use this procedure on a file not opened 
for write access or read write access will return 
CYE$INCORRECT_OUTPUT_REOUEST in the status 
variable. 
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CYP$PUT_PARTIAL_LINE 

C YP$PUT_ PARTIAL _ LINE 

Purpose Writes a string of characters to a text or display file. 

Format CYP$PUT_ PARTIAL. LINE (file, partial_line, last_ 

part _ of _ line, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

partial_line: string ( * <= cyc$max_page_width); 
The string of characters to be written. 

last_part_of_line: boolean; 

Whether or not more cnaracters can oe written to tiie 
current line. If the LAST_PART_OF_LINE parameter is 
TRUE, an end-of-line is appended to the current line after 
the character string is written. If the LAST_PART_OF_ 
LINE parameter is FALSE, subsequent CYP$PUT_ 
PARTIAL_LINE calls may append data to the current 
line. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_ output_ request 
cye$incorrect_ operation 

Remarks 

• For a display file, format control characters are 
automatically prefixed to the beginning of each new 
line. (The format control characters that are used 
depend on what kind of write operation preceded this 
call to CYP$PUT_PARTIAL_LINE.) In addition, if the 
LAST_PART_OF_LINE parameter is TRUE and 
displaying the current line causes the display page 
length to be exceeded, the page overflow mechanism is 
executed. 

• If the length of the current line exceeds the page 
width, the line will be truncated. 
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• 



Attempting to use this procedure on a file not opened 
as a text or display file will return 
CYE$INCORRECT_OPERATION in the status 
variable. 

Attempting to use this procedure on a file not opened 
for write or read write access will return 
CYE$INCORRECT_OUTPUT_REQUEST in the status 
variable. 
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CYP$WRITE_END_OF_LINE 

CYP$WRITE _END _GF_LINE 

Purpose Writes an end-of-line to a text or display file. 

Format CYP$WRITE_ END _OF_ LINE (file, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect _output _ reque st 
cye$incorrect_ operation 

Remarks • If the last write to the file was partial, that line is 
completed; otherwise, an empty line results. 

• Attempting to use this procedure on a file not opened 
as a text or display file will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 

• Attempting to use this procedure on a file not opened 
for write or read write access will return 
CYE$INCORRECT_OUTPUT_REQUEST in the status 
variable. 
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CYP$FLUSH_LINE 

Purpose Flushes the line buffer for a text or display file. 

Format CYP$FLUSH_LINE (file, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

status: VAR of ost$status; 

Status variable in which the completion status is 



Conditions 



Remarks 



returned. 

cye$file_not_open 

cye$incorrect_output_request 

cye$incorrect_operation 

• If the line buffer contains data, the line is terminated 
and then written to the specified file. If the line buffer 
contains no data, this procedure results in no 
operation on the file. 

• Attempting to use this procedure on a file not opened 
as a text or display file will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 

• Attempting to use this procedure on a file not opened 
for write or read write access will return 
CYE$INCORRECT_OUTPUT_REQUEST in the status 
variable. 
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CYPSTAB FILE 



Purpose Positions a text or display file to a specified column or 

position within a line. 



Format 



CYP$TAB = FILE (file, tab _ column, status) 



Parameters file: cyt$file; 

File identifier established when the file was opened. 

tab_column: cyt$page_ width; 

The column to which the file should be positioned. 

status: VAR of ost$status; 

t^LCLtua viaxxauic xii wiuui nie i;uiiipietiuxi aiatub i» 

returned. 

Conditions cye$file_not_open 

cye$incorrect_output_ request 
cye$incorrect_ operation 

Remarks • This procedure performs a write to the file. 

• If the TAB _ COLUMN parameter is less than or equal 
to the file's current column, this procedure does 
nothing. Otherwise, sufficient space characters are 
written to the file so that the next partial write to the 
file will begin at the column specified by TAB_ 
COLUMN. 

• If the TAB_COLUMN parameter is larger than the 
page width of the device associated with the file, line 
truncation will occur when the line is written. 

• Attempting to use this procedure on a file not opened 
as a text or display file will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 

• Attempting to use this procedure on a file not opened 
for write or read write access will return 
CYE$INCORRECT_OUTPUT_REQUEST in the status 
variable. 
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CYP$SKIP_ LINES 

Purpose Writes one or more blank lines to a text or display file. 

Format CYP$SKIP_ LINES (file, number _ of _ lines, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

number_of_iines: integer; 

The number of blank lines to be written. If the last write 
to the file was partial, that line is first completed and 
then the number of blank lines specified by this 
parameter are written to the file. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_ output_ request 
cye$incorrect_ operation 

Remarks • If the file was opened as a display file and the 

NUMBER_OF_LINES parameter was specified as -1, 
the next line written to the file will overwrite the 
current line. In addition, if the NUMBER_OF_ LINES 
plus the current line number exceeds the display page 
size, the page overflow mechanism will be executed. 
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as a text or display file will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 

Attempting to use this procedure on a file not opened 
for write or read write access will return 
CYE$INCORRECT_OUTPUT_REQUEST in the status 
variable. 
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CYPSFILE = CONNECTED = TO_TERMINAL Function 
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Purpose Determines whether or not a text or display file is 

connected to a terminal. 

Format CYP$FILE_CONNECTED_TO_TERMINAL (file): 

boolean; 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

Remarks • Returns a value of TRUE if the file is connected to a 
terminal. Otherwise, a value of FALSE is returned. 

• This function may be used to determine whether the 
calling program needs to limit line size or perform any 
special data formatting for terminal files. 

• Attempting to use this function on a file not opened as 
a text or display file will return CYE$INCORRECT_ 
OPERATION in the status variable. 
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CYP$CURRENT_COLUMN Function 

Purpose Returns the current column within the current line of a 

text or display file. 

Format CYP$CURRENT_ COLUMN (file): cyt$page_ width; 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

Remarks • This function returns the column at which the next 
read or write will begin. 

• Attempting to use this function on a file not opened as 
a text or display file will return an undefined result. 
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CYP$PAGE_WIDTH Function 
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Purpose Returns the page width associated with a text or display 

file. 

Format CYP$PAGE_ WIDTH (file): cyt$page_ width; 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

Remarks Attempting to use this function on a file not opened as a 
text or display file will return an undefined result. 
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Program Examples Using Text and Display Files 

The following example illustrates the use of text file procedures for 
copying one text file to another. Only data between selected columns 
on the old file is written to the new file, and within those columns 
trailing space characters are deleted. 

Example 1: Copy Column Range of Text File 

MODULE truncate; 

* copyc cyp$open_f i 1 e 

*copyc cyp$close f i le 

•copyc cyp$get_next_l ine 

*copyc cyp$put_next_l ine 

•copyc cyp$write_end_of line 

•copyc cyp$write_end_of_block 

•copyc cyp$write_end ofpart it ion 

•copyc cyp$current_fi le_position 



PROGRAM truncate; 

CONST 

in_name = 'OLD"' , 
out name = 'NEW, 
leftmostcolumn # = 11, 
rightmost_co1umn_# = 72; 

VAR 

in file: cyt$file, 

out_file: cyt$file, 

i n_f i 1 especs : cyt $f i 1 e_spec i f i cat i ons , 

out_file_specs: cyt$file_specif i cat ions, 

iine_ptr: "string ( • <= cyc$max_page_width), 

line_length: integer, 

status: ost$status; 

PUSH in_file_specs: [1 .. 4]; 

infi lespecs" [1]. selector := cyc$file_kind; 

infi lespecs" [1] .f ile_lcind := cyc$text_fi le; 

infil e_specs " [2]. se lector := cyc$f i 1 e_access ; 

infi le_specs" [2] .f i leaccess := cyc$read; 

in fi lespecs" [3]. selector := cyc$f i le_existence; 

in filespecs* [3] .f i le_existence := cyc$old_f ile; 

infi lespecs" [4]. selector := cyc$open position; 
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inf i lespecs* [4] .openposition := cyc$beginning; 

PUSH out_file_specs: [1 .. 33; 

out_f ile_specs" [1]. selector := cyc$f ile_kind; 

outf ilespecs* [1] .fi le_kind := cyc$text_fi le; 

out_f i1e_specs" [2]. selector := cyc$f ileaccess; 

out_f i 1 e_specs* [ 2 ] . f i 1 e_access : = cyc$wr i te ; 

out_f i le_specs* [3]. selector := cyc$open_position; 

out_f i le_specs" [3] .open position := cycSbeginning; 

ALLOCATE lineptr: [rightmost_column_#] ; 

cyp$open_file (inname, inf i le_specs, in file, status); 
IF NOT stat us. normal THEN 

RETURN; { > 

IFEND; 

cyp$open_f i le (out_name, out_f i le_specs, out_file, status); 

IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

/mainloop/ 
WHILE status. normal DO 

cyp$get_next_line (infile, line_ptr", line_ length, 

status) ; 
IF NOT status. normal THEN 

EXIT /mainloop/; 
IFEND; 

CASE cyp$current file position (infile) OF 
= cyc$end_of_partition = 
cyp$write_end_of_partition (out_file, status); 
IF NOT stat us. normal THEN 

EXIT /mainloop/; 
IFEND; 
= cyc$end of block = 
cyp$write_end_of_block (out_file, status); 
IF NOT status. normal THEN 

EXIT /mainloop/; 
IFEND; 
= cyc$end_of_information = 

EXIT /mainloop/; 
ELSE 
WHILE (linejength > left most _column_#) AND (line_ptr" 
(line_length) = ' ') DO 

line_length := line_length - l; 
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WHILEND; 

linelength := line_length - leftmost_column_# + 1; 

IF linejength > THEN 

cyp$put_next_line (out file, line_ptr" 

(leftmost_column_#, line_ length), status); 
ELSE 

cyp$write_end_of_line (out file, status); 
I FEND; 
IF NOT status. normal THEN 

EXIT /mainloop/; 
IFEND; 
CASEND; 
WHILEND /mainjoop/; 

cyp$close_fi le (infile, cyc$beg inning, status); 
IF NOT st at us. normal THEN 

RETURN; { > 

IFEND; 

cyp$close_f i le (out_file, cycSbeginning, status); 

IF NOT st at us. normal THEN 

RETURN; { > 

IFEND; 

FREE line_ptr; 

PROCEND truncate; 

MODEND truncate; 
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The following example illustrates the use of display and text file 
procedures. Note the procedure for processing page-overflow. (The 
display file procedures are described later in this chapter.) 

Example 2: Display a Text File 

MODULE display_f i le_example; 

•copyc cyp$open_f lie 

*copyc cyp$close_f i le 

*copyc cyp$current_f i le_position 

•copyc cyp$current_display_l ine 

*copyc cyp$get_partial_line 

•copyc cyp$display_page_ length 

•copyc cyp$tab_file 

•copyc cyp$skip_l ines 

•copyc cyp$position_display_page 

•copyc cyp$put_partial_line 

*copyc cyp$wr i te_end_of_l i ne 

•copyc cyp$display_page_eject 

•copyc cyp$current_page_number 



CONST 

in_name = 'TEXFILE'; 

VAR 

file_numt>: integer := 1, 
recordnumb: integer := 1; 



PROGRAM list; 

CONST 
out_page_width = 80, 
out_page_ length = 50, 

footing_line_number = out_page_ length - 2, 
out_name = 'OUTPUT'; 

VAR 

inf i le_specs: cyt$f i le_specif ications, 
out_f i le_specs: cyt$file_specif ications, 
infile: cyt$file, 
out_file: cyt$file, 
line: string (80), 
line_length: integer, 
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eol : boolean, 
status: ost$status; 

PROCEDURE my _new_page_proc (printfile: cyt$file; 
next pagenumber : i nt eger ; 
VAR status: ost$status); 

VAR 

strholder: string (10), 
str length: integer; 

cyp$display_page_eject (printfile, status); 
IF NOT stat us. normal THEN 

RETURN; { > 

IFEND; 

cyp$put_partial_line (print_file, 'LISTING OF ', FALSE, 

status); 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$put_partial_line (print_f ile, inname, FALSE, status); 

IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$tab_file (printfile, 50, status); 

IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$put_partial_line (print_file, 'FILE ', FALSE, status); 

IF NOT status. normal THEN 

ncTiinn r ... . «. 

r\i_ i urwi , x *• 

IFEND; 

STRINGREP (str_holder, str_length, file_numb); 

cyp$put_partial_line (print_file, str holder 

(1, str_length), FALSE, status); 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$put_partial_line (print_file, RECORD ', FALSE, ', 

status); 
IF NOT st at us. normal THEN 

RETURN; { > 

IFEND; 

STRINGREP (strjiolder, str length, record_numb); 

cyp$put_partial_line (print_file, str holder 
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(1, strlengthj, TRUE, status); 
IF NOT st at us. normal THEN 

RETURN; { > 

I FEND; 

cyp$skip_ lines (print_file, 2, status); 

IF NOT stat us. normal THEN 

RETURN; { > 

IFEND; 

PROCEND my new page proc; 



PROCEDURE printpagefooter (printfile: cyt$file; 
VAR status: ost$status); 

VAR 

str holder: string (3), 
st r_ length: Integer, 
pagenumber : i nt eger ; 

cyp$put_part ial_1 ine (printfile, ' ', TRUE, status): 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

pagenumber := cyp$cur rent pagenumber (printfile); 

cyp$tab_file (print_file, 70, status); 

IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$put_partial_line (print file, 'PAGE ', FALSE, status); 

IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

STRINGREP (str holder, str length, pagejiumber ) ; 

cyp$put_partial_line (print_file, strholder 

(1, str_length), TRUE, status); 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

PROCEND printpagefooter ; 

PUSH in_file_specs: [1 . . 4]: 

inf i le_specs* [1]. selector := cyc$fi lekind; 

in f i lespecs* [1] .f i le_kind := cyc$text_f ile; 
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inf i le_specs" [2]. selector := cyc$file_access; 

in_file_specs" [2] .fi le access := cyc$read; 

in filespecs" [3]. selector .= cyc$f i le_existence; 

infilespecs* [3] .f i le_existence := cyc$old_f ile; 

in_file_specs" [4]. selector := cyc$open_position; 

infilespecs" [4] .open position := cyc$beginning; 

PUSH out_file_specs: [1 .. 6]; 
outfilespecs* [1]. selector := cyc$f i le_kind; 
out_f ile_specs* [1].f ile_kind := cyc$display f i le; 
outf ile_specs" [2]. selector := cyc$fi le_access; 
out_f i le specs" [2] .f ileaccess := cyc$write; 
out_f i le_specs" [3]. selector := cyc$f i leexistence,- 
outf i lespecs" [3] .f i le_existence := cyc$new_or_old_fi le; 
out_f i le_specs" [4]. selector := cyc$page_width; 
outf i le_specs" [4] .page_width := out_page_width; 
out_fi lespecs" [5]. selector := cyc$page length; 
out_file_specs" [5] .page_ length := out_page_length; 
outf i lespecs" [6]. selector := cyc$new_page_procedure; 
out_file_specs* [6] .new_page_procedure.kind := 

cyc$user_spec i f i ed_procedure ; 
out_f i le_specs" [6]. new_page_procedure . user procedure := 

"my new_page_proc ; 

cyp$open_file (inname, in file specs, infile, status); 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$open_f i 1 e (out name, outf i 1 e_specs , out file, status); 

IF NOT status. normal THEN 



IFEND; 

/mainloop/ 
WHILE TRUE DO 

cyp$get_partial_line (infile, line, linejength, eol , 

status); 
IF NOT st at us. normal THEN 

EXIT /mainloop/; 
IFEND; 

CASE cyp$current_file_position (in file) OF 
= cyc$end_of_information = 

cyp$position_display_page (out_file, footing_line_number, 
status); 
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IF NOT stat us. normal THEN 

EXIT /mainloop/; 
I FEND; 

print_page_footer (out_file, status); 
IF NOT stat us. normal THEN 

EXIT /ma in! oop/; 
IFEND; 
EXIT /mainloop/; 

= cyc$end_of_partition = 
file_numb := file_numb + 1; 
record_numb : = 1 ; 
cyp$position_display_page (out_file, footinglinejiumber, 

status); 
IF NOT status. normal THEN 

EXIT /mainloop/; 
IFEND; 

printpagefooter (outfile, status); 
IF NOT status. normal THEN 

EXIT /mainloop/; 
IFEND: 

= cyc$end_of_block = 
record_numb := record_numb + 1; 
cyp$position_display_page (out_file, footing_line_number, 

status); 
IF NOT st at us. normal THEN 

EXIT /mainloop/; 
IFEND; 

print_page_footer (out_file, status); 
IF NOT status. normal THEN 

EXIT /mainloop/; 
IFEND; 

ELSE 

IF cyp$current_display_line (outfile) = 
foot i ng 1 i ne_number THEN 

print_page_footer (out_file, status); 
IF NOT status. normal THEN 

EXIT /mainloop/; 
IFEND; 
IFEND; 

IF linejength > THEN 
cyp$put_partial_line (out_file, line (1, 
line length), eol , status); 
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ELSE 

cyp$write_end_of_line (out_file, status); 
IFEND; 
IF NOT status. normal THEN 

EXIT /main loop/; 
IFEND; 
CASEND ; 
WHILEND /mainJOOp/; 

cyp$close_f He (in file, cyc$beg inning, status); 
IF NOT status. normal THEN 

RETURN; { > 

IFEND; 

cyp$close_file (out_file, cyc$asis, status); 

IF NOT stat us. normal THEN 

RETURN; { > 

IFEND; 

PROCEND list; 

MODEND display_file_example; 
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Page-Overflow Processing for Display Files 

Page-Overflow Processing for Display Files 

The procedures and functions described in this section are for display 
files only. For more information on the structure of display files, refer 
to Display File Structure earlier in this chapter. 

When the number of lines written to a display file exceeds the file's 
specified page length, the line count is reset to zero, the page 
overflow mechanism is executed, and the line count begins again. 

The page overflow mechanism is the sequence of events performed 
whenever the display-page length is exceeded. These events are the 
following: 

• CYBIL I/O checks whether you have specified your own 
page-overflow procedure on the FILE .SPECIFICATIONS parameter 
of CYP$OPEN_FILE. If you have, your page-overflow procedure is 
called. 

• In the absence of such a procedure, CYBIL I/O checks whether you 
specified the use of standard page headers on the FILE_ 
SPECIFICATIONS parameter. If so, the header will be formatted 
and displayed. 

• If neither a user-specified page-overflow procedure nor the standard 
header has been selected, a page eject is performed. (A format 
control character of 1 is automatically specified.) 

The sequence of events may be approximated as follows: 

get next display line 

IF (line_count + 1) > display page length THEN 

line_count := 

IF user-specified new_page_procedure THEN 

pall iicnr-cnofi-pip^ nrn/*p^nrQ 

ELSEIF standard procedure selected THEN 
perform display page eject 
format and display standard header 
skip 1 line 
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ELSE 



perform display page eject 



IFEND 

IFEND 

display the display line 

Standard page headers are either narrow format or wide format. If the 
page width established when the file was opened is greater than or 
equal to 132, the wide format is selected; otherwise, the narrow 
format is selected. (The page width is specified via the FILE_ 
SPECIFICATIONS parameter on CYP$OPEN_FILE.) 

The standard page headers are formatted as follows: 

Narrow format: 

Line Columns Description of Header 

1 1-46 String contained in the title field of the new_ 

page_procedure record of the FILE_ 
SPECIFICATIONS parameter when the file was 
opened. 

48-55 Date in mm/dd/yy format. 

62-72 'PAGE ' and page number. 

2 1-22 Operating system version. 

48-59 Time in system default format, or if no default is 

available, in hh:mm:ss format. 
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Line Columns Description of Header 



1 1-46 String contained in the title field of the new_ 

page_procedure record of the FILE_ 
SPECIFICATIONS parameter when the file was 
opened. 

48-69 Operating system version, 

91-98 Date in mm/dd/yy format. 

110-121 Time in system default format, or if no default is 
available, in hh:mm:ss format. 

123-132 'PAGE ' and page number 

All fields in the standard headers are displayed left-justified with 
blank fill to the right. 

Standard title lines can be produced from within user-specified new 

page jjiuceuuieb tiiiuugn uiie use u± liic i/ ir$i>i3riini_Djiruiii/ruvi/_ 

TITLE procedure, which is described in the next section. 
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Page-Overflow Processing for Display Files 

The following procedures and functions may be used with display files 
only. These procedures and functions are described in greater detail 
on the following pages. 

CYP$START_NEW_DISPLAY_PAGE 

Calls the CYBIL I/O page overflow mechanism. 

CYP$POSITION_DISPLAY_PAGE 
Positions a display file at a specified line. 

CYP$DISPLAY_STANDARD_TITLE 

Formats and writes a standard title line to a display file. 

CYP$DISPLAY_PAGE_EJECT 

Positions a display file to the top of the next page. 

CYP$DISPLAY_PAGE_LENGTH 

Returns the page length associated with a display file. 

CYP$CURRENT_DISPLAY_LINE 

Returns the number of the current line within the current page of 
a display file. 

CYP$CURRENT_PAGE_NUMBER 

Returns the current page number of a display file. 
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^ ii'jpoi^.rvi__i , >iJLW_i J »ii3i'ij^\i — rAUJi 

Purpose Calls the CYBIL I/O page overflow mechanism. 

Format CYP$START_NEW_DISPLAY_PAGE (display. file, 

status) 

Parameters display_file: cyt$file; 

File identifier established when the file was opened. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_ output _ request 
cye$incorrect_ operation 

Remarks * If the last write to the display file was a partial line 
rather than a full line, that line is terminated and 
then a new display page is started. 

• Attempting to use this procedure on a file not opened 
as a display file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

• Attempting to use this procedure on a file not opened 
for write or read write access will return 
CYE$INCORRECT_OUTPUT_REQUEST in the status 
variable. 
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CYP$POSITION_DISPLAY_PAGE 

Purpose Positions a display file at a specified line. 

Format CYP$POSITION_ DISPLAY. PAGE (display. file, line, 

number, status) 

Parameters display _file: cyt$file; 

File identifier established when the file was opened. 

line _ number: cyt$page _ length; 

The line at which the file is to be positioned. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_output_request 
cye$incorrect_ operation 

Remarks • If the value of the LINE .NUMBER parameter is 

greater than the current line number and less than or 
equal to page size, the file is positioned to that line on 
the current page. If LINE.NUMBER is less than or 
equal to the current line number, the page overflow 
mechanism is executed and the file is positioned at 
LINE.NUMBER on the next page. If LINE. 
NUMBER is greater than the page size, the page 
overflow mechanism is executed and the file will be 

pOSIbiOncu at me top Oi tue next page. 

• If the last write to the display file was a partial write, 
that line is terminated and then the display page is 
positioned. 

• Attempting to use this procedure on a file not opened 
as a display file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

• Attempting to use this procedure on a file not opened 
for write or read write access will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 
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Purpose Formats and writes a standard title line to a display file. 

Format CYP$DISPLAY_ STANDARD, TITLE (file, title, lines, 

after _ title, status) 

Parameters file: cyt$file; 

File identifier established when the file was opened. 

title: string (* < = cyc$title_size); 

The text that is to appear in columns 1 thru 46 in the 
standard title. 

lines after title: cvt$nai?f> Ifinsrth: 

The number of blank lines to appear between the 
standard title and the next display line. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 



Conditions 



Remarks 



cye$file _ not _ open 

cye$incorrect_output_request 

cye$incorrect_operation 

• If the last write to the display file was a partial write, 
that display line is terminated and then the standard 
title is written. 

• Attempting to use this procedure on a file not opened 
as a display file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

• Attempting to use this procedure on a file not opened 
for write or read write access will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 
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C YP$DISPLAY_PAGE __E JECT 

Purpose Positions a display file to the top of the next page. 

Format CYP$DISPLAY_ PAGE _ EJECT (display _file, status) 

Parameters display _ file: cyt$file; 

File identifier established when the file was opened. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

cye$incorrect_output_request 
cye$incorrect_ operation 

Remarks • This procedure should only be called from a 
user-specified page overflow procedure. 



• 



If the last write to the display file was a partial write, 
that line is terminated and then a display page eject 
is performed (with a format control character of 1 in 
column 1). 

Attempting to use this procedure on a file not opened 
as a display file will return CYE$INCORRECT_ 
OPERATION in the status variable. 

Attempting to use this procedure on a file not opened 
for write or read write access will return 
CYE$INCORRECT_ OPERATION in the status 
variable. 
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Purpose Returns the page length associated with a display file. 

Format CYP$DISPLAY_ PAGE .LENGTH (display .file): 

cyt$page_length; 

Parameters display. file: cyt$file; 

File identifier established when the file was opened. 

Remarks Attempting to use this function on a file not opened as a 
display file will return an undefined result. 
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CYP$CURRENT_DISPLAY_LINE Function 

Purpose Returns the number of the current line within the current 

page of a display file. 

Format CYP$CURRENT_DISPLAY_LINE (display. file): 

cyt$page_length; 

Parameters display_file: cyt$file; 

File identifier established when the file was opened. 

Remarks • After any vertical spacing command (such as 

CYP$SKIP_LINES, CYP$DISPLAY_PAGE_EJECT, 
CYP$POSITION_DISPLAY_PAGE), the value returned 
is the next line to be displayed. After a write 
command (such as CYP$PUT_NEXT_LINE, 
CYP$PUT_PARTIAL_LINE, CYP$WRITE_END_OF_ 
LINE), the value returned is the line just displayed. 

• Attempting to use this function on a file not opened as 
a display file will return an undefined result. 
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Purpose Returns the current page number of a display file. 

Format CYP$CURRENT_PAGE .NUMBER (display. file): 

integer; 

Parameters display_file; cyt$file; 

File identifier established when the file was opened. 

Remarks Attempting to use this function on a file not opened as a 
display file will return an undefined result. 
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Program Example Using Terminal I/O 

The following example illustrates the use of display file procedures 
employing terminal I/O. 

Example 1: 

*copyc osd$default_pragmats 

MODULE catenate_string_to_f i le; 

*copyc cyp$get_next_ 1 i ne 

•copyc cyp$put_partial_line 

•copyc cyp$open_f i le 

•copyc cyp$close_f i le 

*copyc cyp$current_f ile_position 

*copyc ost$status 



PROGRAM catenate_string_to_file 
( VAR st at us : ost $st at us ) ; 

CONST 

input_file_name = 'INPUT', 
output_file_name = 'OUTPUT', 
prefix_string = 'INPUT TEXT = "', 
suff ix_string = ""; 

VAR 

chars_read: integer, 

ianore_status: ostSstatus. 

input_line: string (osc$max_string_size) , 

input_file: cyt$file, 

input_f i le_specs: [static, read] array [1 .. 2] of 
cyt$file_spec1fication := [[cyc$f i le_kind, 
cyc$text_fi le], [cyc$f i le_access, cyc$read]], 

output_file: cyt$file, 

output_file_specs: [static, read] array [1 ..2] of 
cyt$file_specification := [[cyc$fi le_kind, 
cyc$text_file], [cyc$fi le_access, cyc$write]]; 



stat us. normal := true; 
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cyp$open_f i 1 e ( i nput_f 1 1 e_name , " 1 nput _f 1 i e_specs , 

input_file, status); 
IF status. normal THEN 

cyp$open_fi le (output_f ile_name, *output_f i le_specs, 
output_file, status); 

IF st at us. norma! THEN 

cyp$get_next_line (input_file, input_line, chars_read, 

status); 
IF st at us. normal THEN 

/read_write/ 
WHILE (cyp$current_fi le_position (input_file) <> 
cyc$end_of_information) do 
cyp$nijt_nart ia1_l ine (output_f1 le, prefix_string, 

false, status); 
IF NOT status. normal THEN 

EXIT /read_write/; 
IFEND; 
cyp$put_partial_line (output_f i le, input_line (1, 

ehars_read) , false, status); 
IF NOT status. normal THEN 

EXIT /read_write/; 
IFEND; 
cyp$put_partial_line (output_f i le, suffix_string, 

true, status); 
IF NOT status. normal THEN 

EXIT /read_write/; 
IFEND; 

cyp$get_next_line (input_file, input_line, 

chars_read, status); 
IF NOT st at us. normal THEN 

EXIT /read_write/; 
IFEND; 
WHILEND /read_write/; 
IFEND; 
IFEND; 
IFEND; 
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cyp$close_file (input_file, cyc$default_open_position, 

ignore_status); 
cyp$close_fi le (output.fi le, cyc$default_open_position, 

ignore_status); 

PROCEND catenate_st r i ng_to_f i le; 
MODEND catenate_string_to_file; 
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JNOS/VE-Specific Procedures and 

Functions for CYBIL I/O 13 

This chapter describes the procedures which are available only on the 

CYP$GET_FILE_IDENTIFIER 

CYP$GET_BINARY_FILE_POINTER 

CYP$OPEN_BINARY_FILE 

CYP$OPEN_RECORD_FILE 

CYP$OPEN_TEXT_FILE 

CYP$OPEN_DISPLAY_FILE 



NuS/VE-Specific Procedures and 

Functions for CYBIL I/O 13 

Because they provide access to capabilities unique to NOS/VE, the 
procedures described in this chapter are intended to be used only with 
the NOS/VE implementation of CYBIL I/O. Programs meant to be 
portable between operating systems should minimize use of these 
procedures. 1 

The following are the NOS/VE-specific procedures, which are described 
on the following pages: 

CYP$GET_FILE_IDENTIFIER 

Returns a file's identifier that was established when the file was 
opened. 

C YP$GET_BIN ARY_ FILE _ POINTER 

Returns a pointer to the segment pointer used by CYBIL I/O. 

CYP.$OPEN_BINARY_FILE 

Utilizes the flexibility of the FSP$OPEN_FILE procedure when 
opening binary files. 

CYP$OPEN_RECORD_FILE 

Utilizes the flexibility of the FSP$OPEN_FILE procedure when 
opening record files. 

CYP$OPEN_TEXT_FILE 

Utilizes the flexibility of the FSP$OPEN_FILE procedure when 
opening text files. 

CYP$OPEN_ DISPLAY_FILE 

Utilizes the flexibility of the FSP$OPEN_FILE procedure when 
opening display files. 



1. Currently, CYBIL I/O is only available for NOS/VE. 
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CYP$GET_FILE ^IDENTIFIER 

Purpose Returns a file's identifier that can be used with the access 

method (AM) procedures contained in the NOS/VE 
program interface. 

Format CYP$GET_ FILE .IDENTIFIER (file, file .identifier, 

status) 

Parameters file: eyt$file; 

File identifier established when the file was opened. 

file .identifier: VAR of amt$file_identifier; 

The file access identifier that uniquely identifies and is 
subsequently used to reference this instance of open. 

status: ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$file_not_open 

Remarks The file access identifier returned by this procedure may 
be used on calls to access-method procedures such as 
AMP$FETCH which are specific to an instance of open. 
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Purpose 



Format 



Returns a pointer to the segment pointer used by CYBIL 
I/O. 

CYP$GET_ BINARY. FILE .POINTER (file, binary, 
file _ pointer, status) 



Parameters file: cyt$file; 

File identifier established when the file was opened. 

binary _file_pointer: VAR of A amt$segment_pointer; 

status: VAR of ost$status; 

Status variable in which the completion status is 



Conditions 



Remarks 



returned. 

cye$file _ not _ open 
cye$incorrect_ operation 

• This procedure allows you to direct the reading or 
writing of binary files when the CYP$PUT_NEXT_ 
BINARY and CYP$GET_NEXT_ BINARY procedures 
are not adequate. (For example, when pointer 
information is to be stored as part of the data to be 
written). 

• Binary files are read and written using segment 
access. The CYP$GET_BINARY_FILE_POINTER 
procedure returns a pointer to the segment pointer 
that CYBIL I/O uses. CYBIL I/O gets the segment 
pointer as a sequence pointer (that is, the kind field of 
the segment pointer record is AMC$SEQUENCE_ 
POINTER). The sequence pointer may be accessed by 
referencing the sequence_pointer field of the segment 
pointer. For example: 

NEXT variable.po inter IN segnient_poir!ter~.sequence_po1nter; 
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CYP$OPEN_BINARY_FILE 

Purpose Utilizes the flexibility of the FSP$OPEN_FILE procedure 

when opening binary files. 

Format CYP$OPEN _ BIN ARY_ FILE (file_name, file.access, 

file _ attachment, default_creation _ attribute, 
mandated _ creation _ attribute, attribute _ validation, 
attribute _ override, file _ control, status) 



Parameters file_name: cyt$file_name; 

Name of the file to be opened. On NOS/VE, a file name 
may be up to 512 characters in length, and can be a file 
reference. 

file_aecess: cyt$file_access; 

Permitted mode of access. The following values are 
defined: 

CYC$READ 
Read access only. 

CYC$WRITE 
Write access only. 

CYC$READ_WRITE 
Read or write access. 

file _ attachment: "fst$attachment_options; 

The attachment options in effect for the requested 
instance of open. 

ucioun_uBttuuii_amiuun;; isi.$iiie cycie auriDures; 

A pointer to a record of file cycle attributes established 
for a file that is initially opened or created by this call. 

mandated _ creation _ attribute: *fst$file_cycle_ 
attributes; 

A pointer to a record of file cycle attributes established 
for a file that is initially opened or created by this call. 
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A pointer to a record of required attribute values for the 
file or file cycle. 

attribute _ override : A fst$file _cycle _ attributes ; 

A pointer to a record of attribute values to be overridden 
for this instance of open. 

file .control: VAR of cyt$file; 

Returns a file identifier that must be used on all other 
calls to the file. This is a unique identifier used for the 
file while it is open; any other references to this file must 
include this identifier. 

AU.. AJ_„ ±„ __11 „ flVDTT T//~4 1 :j.T- 
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undefined or altered pointer will have unpredictable 
results. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$no_ memory _ to _open_ file 
cye$incorrect_open_request 

Remarks • The values specified for the FILE .ATTACHMENT, 
DEFAULT. CREATION_ATTRIBUTE, MANDATED. 
CREATION.ATTRIBUTE, ATTRIBUTE. VALIDATION, 
and ATTRIBUTE .OVERRIDE parameters are passed 
directly to the FSP$OPEN_FILE procedure.The values 
passed in these parameters are not validated or 
checked in any way. 

• For more information on the FSP$OPEN_FILE 

procedure and its parameters, refer to the CYBIL for 
NOS/VE File Management manual. 
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C YP$OPEN_RECORD ..FILE 

Purpose Utilizes the flexibility of the FSP$OPEN_FILE procedure 

when opening record files. 

Format CYP$OPEN_ RECORD. FILE (file_name, file_access, 

file _ attachment, default _ creation _ attribute, 
mandated _ creation _ attribute, attribute _ validation, 
attribute _ override, file _ control, status) 

Parameters file_name: cyt$file_name; 

Name of the file to be opened. On NOS/VE, a file name 
may be up to 512 characters in length, and can be a file 
reference. 

file_access: cyt$file_access; 

Permitted mode of access. The following values are 
defined: 

CYC$READ 
Read access only. 

CYC$WRITE 
Write access only. 

CYC$READ_WRITE 
Read or write access. 

file _ attachment: " f st$attachment_ options ; 

The attachment options in effect for the requested 
instance of open. 

default _ creation _ attribute : * fst$fiie _ cycle _ attributes ; 

A pointer to a record of file cycle attributes established 
for a file that is initially opened or created by this call. 

mandated _ creation _ attribute: ,l fst$file_cycle_ 
attributes; 

A pointer to a record of file cycle attributes established 
for a file that is initiall v opened or created by this call 
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attriDuie_ validation: "ist$ine_cycie_attributes; 

A pointer to a record of required attribute values for the 
file or file cycle. 

attribute_overri.de: A fst$file_cycle_attributes; 

A pointer to a record of attribute values to be overridden 
for this instance of open. 

file .control: VAR of cyt$file; 

Returns a file identifier that must be used on all other 
calls to the file. This is a unique identifier used for the 
file while it is open; any other references to this file must 
include this identifier. 



O^T - iTT 



Attempting to can a uirsiLi i/u proceaure witn an 
undefined or altered pointer will have unpredictable 
results. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$no_memory_to_open_file 
cye$incorrect_open_request 

Remarks • The values specified for the FILE_ATTACHMENT, 
DEFAULT_CREATION_ATTRIBUTE, MANDATED. 
CREATION_ATTRIBUTE, ATTRIBUTE _ VALIDATION, 
and ATTRIBUTE_OVERRIDE parameters are passed 
directly to the FSP$OPEN_FILE procedure. The 
values passed in these parameters are not validated or 
checked in any way. 

• For more information on the FSP$OPEN_FILE 

procedure and its parameters, refer to the CYBIL File 
Management manual. 
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CYP$OPEN_TEXT_FILE 

Purpose Utilizes the flexibility of the FSP$OPEN_FILE procedure 

when opening text files. 

Format CYP$OPEN_TEXT_FILE (file_name, file_access, 

file _ attachment, default _ creation _ attribute, 
mandated _ creation _ attribute, attribute _ validation, 
attribute _ override, file _ control, status) 



Parameters file_name: cyt$file_name; 

Name of the file to be opened. On NOS/VE, a file name 
may be up to 512 characters in length, and can be a file 
reference. 

file_access: cyt$file_access; 

Permitted mode of access. The following values are 
defined: 

CYC$READ 
Read access only. 

CYC$WRITE 
Write access only. 

CYC$READ_WRITE 
Read or write access. 

file _ attachment: A fst$attachment_options; 

The attachment options in effect for the requested 
instance of open. 

default _ creation _ attribute : " f st$fiie _ cycle _ attributes; 

A pointer to a record of file cycle attributes established 
for a file that is initially opened or created by this call. 

mandated _ creation _ attribute : A fst$file _ cycle _ 
attributes; 

A pointer to a record of file cycle attributes established 
for a file that is initially onened or created by this call 
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attribute _ validation : * fst$fiie _ cycle _ attributes ; 

A pointer to a record of required attribute values for the 
file or file cycle. 

attribute .override: *fst$file_cycle_attributes; 

A pointer to a record of attribute values to be overridden 
for this instance of open. 

file _ control: VAR of cyt$file; 

Returns a file identifier that must be used on all other 
calls to the file. This is a unique identifier used for the 
file while it is open; any other references to this file must 
include this identifier. 

Attempting to call a CYBIL 1/0 procedure with an 
undefined or altered pointer will have unpredictable 

results. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$no_memory_to_open_file 
cye$incorrect_open_request 

Remarks • The values specified for the FILE_ATTACHMENT, 
DEFAULT_CREATION_ATTRIBUTE, MANDATED. 
CREATION_ATTRIBUTE, ATTRIBUTE_VALIDATION, 
and ATTRIBUTE_OVERRIDE parameters are passed 
directly to the FSP$OPEN_FILE procedure.The values 
passed in these parameters are not validated or 
checked in any way. 

• For more information on the FSP$OPEN_FILE 

procedure and its parameters, refer to the CYBIL for 
NOS/VE File Management manual. 
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CYP$OPEN_DISPLAY__FILE 

Purpose Utilizes the flexibility of the FSP$OPEN_FILE procedure 

when opening display files. 

Format CYP$OPEN_ DISPLAY. FILE (file_name, file_access, 

file _ attachment, default _ creation _ attribute, 
mandated _ creation _ attribute, attribute _ validation, 
attribute _ override, file.control, status) 



Parameters file_name: cyt$file_name; 

Name of the file to be opened. On NOS/VE, a file name 
may be up to 512 characters in length, and can be a file 
reference. 

file_access: cyt$file_access; 

Permitted mode of access. The following values are 
defined: 

CYC$READ 
Read access only. 

CYC$WRITE 
Write access only. 

CYC$READ_WRITE 
Read or write access. 

file .attachment: A fst$attachment_options; 

The attachment options in effect for the requested 
instance of open. 

uciauu_t;icauuu_atuiuuu:. isi/«piiie_cycie_aLLriDutes; 

A pointer to a record of file cycle attributes established 
for a file that is initially opened or created by this call. 

mandated .creation .attribute: A fst$file_cycle_ 
attributes; 

A pointer to a record of file cycle attributes established 
for a file that is initially opened or created by this call. 
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attribute _ validation : * f st$file _ cycle _ attributes ; 

A pointer to a record of required attribute values for the 
file or file cycle. 

attribute _ override: "fst$file_cyele_attributes; 

A pointer to a record of attribute values to be overridden 
for this instance of open. 

file _ control: VAR of eyt$file; 

Returns a file identifier that must be used on all other 
calls to the file. This is a unique identifier used for the 
file while it is open; any other references to this file must 
include this identifier. 

.i-ikuempiiiig vu can a i^idil ukj pruceuure wiui tui 

undefined or altered pointer will have unpredictable 
results. 

status: VAR of ost$status; 

Status variable in which the completion status is 
returned. 

Conditions cye$no _ memory _ to _ open _ file 
cye$incorrect _ open_ request 

Remarks • The values specified for the FILE _ ATTACHMENT, 
DEFAULT_CREATION_ATTRIBUTE, MANDATED. 
CREATION. ATTRIBUTE, ATTRIBUTE. VALIDATION, 
and ATTRIBUTE.-OVERRIDE parameters are passed 
directly to the FSP$OPEN_FILE procedure. The 
values passed in these parameters are not validated or 
checked in any way. 

• For more information on the FSP$OPEN_FILE 

procedure and its parameters, refer to the CYBIL for 
NOS/VE File Management manual. 
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Access Attribute ASID 



liiossary 



Access Attribute 

Characteristic of a variable that determines whether the variable can 
be both read and written. Specifying the access attribute READ makes 
the variable a read-only variable. 

Active Call Chain 

List of calls that led to the current procedure. 

Active Segment Identifier (ASID) 

A 16-bit field in the system virtual address (SVA) that uniquely 
identifies an active segment in the system. The segment number in 
the process virtual address (PVA), which is known locally to the 
program, is converted to the active segment identifier, which is known 
globally to the system. See also Process Virtual Address and System 
Virtual Address. 

Alphabetic Character 

One of the following letters: 

A through Z 

a through z 
See also Character and Alphanumeric Character. 

Alphanumeric Character 

An alphabetic character or a digit. See also Character, Alphabetic 
Character, and Digit. 

ANSI 

American National Standards Institute. 

ASCII 

American Standard Code for Information Interchange. 

ASID 

See Active Segment Identifier. 
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Assignment Statement Character 

Assignment Statement 

A statement that assigns a value to a variable. 

B 

Batch Debugging 

Debugging when the user has no direct control of debugging during 
program execution. Contrast with Interactive Debugging. 

BDP 

Business data processing. 

Bit 

A binary digit. A bit has a value of or 1. See also Byte. 

Boolean 

A kind of value that is evaluated as TRUE or FALSE. 

Break 

The primary mechanism for Debug to gain control from an executing 
program. A break specifies an event and an address range such that 
when the event occurs within the address range, Debug takes control. 

Byte 

A group of contiguous bits. For NOS/VE, one byte is equal to 8 bits. 
An ASCII character code uses the rightmost 7 bits of one byte. 

Byte Offset 

A number corresponding to the number of bytes beyond the beginning 
of a line, procedure, module, or section. 



Character 

A letter, digit, space, or symbol that is represented by a code in one 
or more of the standard character sets. 

It is also referred to as a byte when used as a unit of measure to 
specify block length, record length, and so forth. 

A character can be a graphic character or a control character. A 
graphic character is printable; a control character is nonprintable and 
is used to control an input or output operation. 
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Character Constant Event 

vntiraiskcr vuusuiui 

A fixed value that represents a single character. 

Comment 

Any character or sequence of characters that is preceded by an 
opening brace and terminated by a closing brace or an end of line. A 
comment is treated exactly as a space. 

Compilation Time 

The time at which a source program is translated by the compiler to 
an object program that can be loaded and executed. Contrast with 
Execution Time. 

Compiler 

A processor that accepts source code as input and generates object 
code as output. 

A procedure called when an exception condition occurs. Condition 
handler processing occurs after Debug processing if Debug mode is on. 
The procedure is called only if it has been established as the condition 
handler for the condition type and the condition occurs within its 
scope. 

D 

Delimiter 

The indicator that separates and organizes data. 

Digit 

One of the following characters: 

0123456789 
E 

Entry Point 

The point in a module at which execution of the module can begin. 

Event 

A condition, such as division by zero, that causes Debug to gain 
control. 
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Execution Ring Interactive Debugging 

Execution Ring 

The level of hardware privilege assigned to a procedure while it is 
executing. 

Execution Time 

The time at which a compiled source program is executed. Also known 
as Run Time. 

Expression 

Notation that represents a value. A constant or variable appearing 
alone, or combinations of constants, variables, and operators. 

External Reference 

A call to an entry point in another module. 



Field 

A subdivision of a record that is referenced by name. For example, 
the field NORMAL in a record of type OST$STATUS called OLD_ 
STATUS is referenced as follows: 

OLD_ STATUS.NORMAL 



Integer Constant 

<-»ne or more uigits ana, ior nexaaecimal integer constants, the 
following characters: 

ABCDEFabcdef 

A hexadecimal integer constant must begin with a digit. A preceding 
sign and subsequent radix are optional. 

Interactive Debugging 

Debugging when the user has direct control of the debugging process. 
Contrast with Batch Debugging. 
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Load Module Name 



Load Module 

A module reformatted for code sharing and efficient loading. When the 
user generates an object library, each object module in the module list 
is reformatted and written as a load module on the object library. 

M 

Machine Addressing 

Use of actual machine addresses. Contrast with Module Addressing 
and Symbolic Addressing. 

Machine-Level Debugging 

Debugging using machine-level terms such as machine addresses. A 
knowledge of machine architecture is required. Contrast with Symbolic 
Debugging. 

Module 

A unit of text accepted as input by the loader, linker, or object 
library generator. See also Object Module and Load Module. 

Module Addressing 

Use of addresses in terms of module and procedure names and an 
offset. Contrast with Machine Addressing and Symbolic Addressing. 

N 

Name 

Combination of from 1 through 31 characters chosen from the 
following set: 

• Alphabetic characters (A through Z and a through z). 

• Digits (0 through 9). 

• Special characters (#, @, $, and _). 

The first character of a name cannot be a digit. 
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Object Code Range 

o 

Object Code 

Executable code produced by a compiler. 

Object Module 

A compiler-generated unit containing object code and instructions for 
loading the object code. It is accepted as input by the system loader 
and the Object Library Generator. 



Page 

An allocatable unit of real memory. 

Pointer Variable 

A CYBIL variable which contains the virtual address of a value. 

PP 

Peripheral processor. 

Process Virtual Address (PVA) 

The virtual address known locally by a program (or process). It is 
converted to a system virtual address (SVA) that is known globally by 
the system. It consists of a ring number, a segment number, and a 
byte number. The segment number is used to form the active segment 
identifier in the system virtual address. See also Active Segment 
Identifier and System Virtual Address. 

PVA 

See Process Virtual Address. 

R 

Range 

Value represented as two values separated by an ellipsis. The element 
is associated with the values from the first value through the second 
value. The first value must be less than or equal to the second value. 
For example: 

1 .. 100 
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Symbolic Addressing Variable Attribute 

Symbolic Addressing 

Use of addresses in source program terms such as program names and 
line numbers. Contrast with Machine Addressing and Module 
Addressing. 

Symbolic Debugging 

Debugging using source program terms such as line numbers and 
program names. Contrast with Machine-Level Debugging. 

System Virtual Address (SVA) 

The virtual address known globally by the system. It is formed using 
the process virtual address, which is known locally by a program. It 
consists of an active segment identifier and a byte number. The 
system virtual address is translated into the real memory address. See 
also Active Segment Identifier and Process Virtual Address. 



Traceback 

A list of procedure names within a program, beginning with the 
currently executing procedure, proceeding backward through the 
sequence of called procedures, and ending with the main program. 



Variable 

Represents a data value. 

Variable Attribute 

A characteristic of a variable. See also Access Attribute. 
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Table B-l. Related Manuals 



Manual Title 



Publication Online 
Number Manuals 1 



Sfka Mann alo< 
j.v«^ irxuiiuuioi 

CYBER Initialization Package (CIP) 60457180 

User's Handbook 

NOS/VE Accounting and Validation 60458910 

Utilities for Dual State 

Usage 

NOS/VE Accounting Analysis System 60463923 
Usage 

Family Administration for NOS/VE 60464513 

Usage 

NOS/VE Operations 60463914 

Usage 

NOS/VE System Analyst Reference 60463915 

Set 

System Performance and Maintenance 

Usage 

NOS/VE System Analyst Reference 60463916 

Set 

Network Interface 

Usage 

NOS/VE System Analyst Reference 60463917 

Set 

LCN Configuration and Network 

Management 

Usage 

CYBER 930 Computer System 60469560 

Basic Operations 

Usage _^ 

1. This column lists the title of the online version of the manual and 
indicates whether the examples in the printed manual are in the 
online Examples manual. 
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Table B-l. Related Manuals (Continued) 



Manual Title 


Publication 
Number 


Online 
Manuals 1 


SCL Manuals (Continued): 






SCL for NOS/VE 
Quick Reference 


60464018 


SCL 


SCL for NOS/VE 
Advanced File Management 
Tutorial 


60486412 


AFM_T 


SCL for NOS/VE 
Advanced File Management 
Usage 


60486413 


AFM 


SCL for NOS/VE 
Advanced File Management 
Summary 


60486419 




EDIT_ CATALOG 
Usage 




EDIT_ 
CATALOG 


EDIT_ CATALOG for NOS/VE 


60487719 





Summary 

Screen Design Facility for NOS/VE 
Usage 

Screen Formatting for NOS/VE 

TT 

Screen Formatting for NOS/VE 
Quick Reference 



60488613 SDF 



60488813 EXAMPLES 



SCREEN_ 
FORMATTING 



1. This column lists the title of the online version of the manual and 
indicates whether the examples in the printed manual are in the 
online Examples manual. 
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Table B-l. Related Manuals (Continued) 



Manual Title 



Publication Online 
Number Manuals 1 



FORTRAN Manuals (Continued): 

FORTRAN Version 2 for NOS/VE 
Language Definition 

Usage 

FORTRAN for NOS/VE 

Topics for FORTRAN Programmers 

Usage 

FORTRAN for NOS/VE 
Quick Reference 

FORTRAN Version 2 for NOS/VE 
Quick Reference 

FORTRAN for NOS/VE 
Summary 

COBOL Manuals: 

COBOL for NOS/VE 
Tutorial 

COBOL for NOS/VE 
Usage 

COBOL for NOSA r E 

Summary 



60487113 EXAMPLES 



60485916 



60485919 



60486012 



60486013 



FORTRAN 



VFORTRAN 



COBOL_T 



COBOL 



1. This column lists the title of the online version of the manual and 
indicates whether the examples in the printed manual are in the 
online Examples manual, 
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i-g spmuBw pa^Biay 



£ uoisiAay 



(pdtmpuoQ) 



jbiiubui saidurexg auquo 

aq^ ux 3jb [Btitrera pa^uud aq; in sajdurexa aq:j laq^aqM sa^BDrptn 

pxiB {BnuBtn aq^ jo uotsaaA auquo aq^ jo apt} aip s^sq urarqoa spqj, x 



OOlOHd 8U98*09 

STL98t09 
6I9S8?09 

IVOSVd £1988*09 

81398*09 

6IS98t09 

0ISV9 SIS98t09 

EI8S8t09 

H8S8*09 



aouaaajay iptnfo 
3A/S0N JOJ Sopjj 

aSBsn 
3A/SON JOJ Sopjd 

pjB^ £reuiunig 
3A/S0N JOJ F»SBd 

aSssfi 
3A/S0N J0 J F 3SB d 

aSBsn 

ii 

3A/S0N -">J dSH 

pjBQ XaBuiuing 
3A/S0N joj 0ISV3 

aSBSfi 
3A/S0N -toj 0ISV9 

aSBSfi 
uot^nnjaQ aSBnSuBq 

3A/S0N JO J IdV 
aSBsn 

sa mron 9 im 

3A/SON JOJ IdV 
:spsnnB]/V[ jafidmoQ «iaqK) 



x siBnuBj\[ jaqumj^ 

auquo uopBDTiqnd 



mVL IBnuB^ 



rtiaflfrtOTirt'l 1 BTwriinaTiT nainian •t.ct ainnT 



siBnnBj^ pajBjajj 



Related Manuals 



Table B-l. Related Manuals (Continued) 



Manual Title 



Publication 
Number 



Online 
Manuals 1 



VX/VE 60469980 

An Introduction for UNIX Users 
Tutorial/Usage 

VX/VE 60469800 

Support Tools Guide 

Tutorial 

VX/VE 60469790 

Programmer Guide 

Tutorial 

VX/VE 60469780 

User Guide 

Tutorial 

VX/VE 60469810 

User Reference 

Usage 

VX/VE 60469820 

Programmer Reference 

Usage 

VX/VE 60469770 

Administrator Guide and Reference 
Tutorial/Usage 

C/VE for NOS/VE C 

Quick Reference 

1. This column lists the title of the online version of the manual and 
indicates whether the examples in the printed manual are in the 
online Examples manual. 
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6-g spmnBjsi pa*BjE>£ 



J UOISIASy 



(panmpzoQ) 



jBnuBui sa[duiBxg axnpio 
aifl ui 9jb pjinreui pa^uud aqi ux sajduiBxa aip jaipaqM sa^BDipur 

pUB p3tlUBUI 3lfl JO U0ISJ3A 3UT[U0 atfl JO 3[^p 3tfl S^STJ UUinjOO STtJJ, X 

_ . ilisQ 

UOTlBJlSTUTOipY BJBQ 

*T068*09 mami 

aSBSf} 

saanpeoojti puBuiuiOQ pus 

'ja^u^ ^loda'jj 'A\ian£) joj spireuiraoQ 

81068*09 WWm 

aSBSQ 

saanpaoojj puBunnoQ 

puB 'ja^u^ ijoday 'Ajanfr 

S 1068*09 ML/HI 

xspsnuBj^ ^uauiagBUBi^ b?bq 

aSBSfi 
apxtif) saossaDoidajj 

03669*09 XA/SMG 

aSBSQ 

apmf) saSB^OBj ojobj^ 

0X669*09 XA/3MCI 

aSssfi 

9 PT n O sjawBiajoj ?xaj, 

00669*09 XA/9MCI 

aSBSfi/[Biio^nx 

aouaaajay aasn P«b uoponpoxiui 

06869*09 XA/aMO 

aSBSfi 
08869*09 3A/S0N ™} 3A/0 

:(panupuoo) sp3nuBH[ HA/XA 



auifuQ uopBOnqnj 



mn ren«BW 



fvanmnion) stbtiubtat naiBTau *T-a 9tqbt 



sjenuBj^ pa^ay 



Related Manuals 



Table B-l. Related Manuals (Continued) 



Manual Title 


Publication 
Number 


Online 
Manuals 1 


Data Management Manuals 
(Continued): 






IM/DM 

Application Programming 

Usage 


60489015 




IM/Quick for NOS/VE 
Tutorial 


60485712 




IM/Quick for NOS/VE 
Summary 


60485714 




IM/Quick for NOS/VE 

US3.£T6 




QUICK 


IM/DM for NOS/VE 




IM_DM 



Quick Reference 

CDCNET Manuals: 

CDCNET Commands 
Quick Reference 

CDCNET Product Descriptions 

CDCNET Conceptual Overview 

CDCNET Configuration and Site 
Administration Guide 



nnnnTnm -*T 



uuwuiii xxetworK uperauons 

CDCNET Network Performance 
Analyzer 

CDCNET Network Analysis 



60000020 

60460590 
60461540 
60461550 

60461520 
60461510 

60461590 



1. This column lists the title of the online version of the manual and 
indicates whether the examples in the printed manual are in the 
online Examples manual . 
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TT-g spmuBft pa^ay 



j uotstAay 



(paniipvo£)) 



•pnireui sa^duiBxg auijuo 

aipj in axe pnireui pa^uud aifl ui sajdorexa aqj jaqjaqM sa^Boipin 

pire [BnuBirt ai$ jo uoxsjsa aux^no aipi jo 3131:1 aq^ s^sxj uuinioo siqj, x 



HOXVH 



ssaoov 



89889*09 



09889*09 
08889*09 



02*39*09 



0T*Z9*09 
00*39*09 
00919*09 



8 PPD J9Sfi 

aDTAea qa^g xaNoao 

aouajajay jpnif) 

3A/S0N 
joj aoBjaa^ui [BUTOuax xaNOdO 

aSBSQ 
aoBjaa^ui jBurauax xaNOCIO 

ssaoay xaNoao 

s^ooo^ojcj ^jOAiia^j 

S aumiOA 

aauajaja'a; 

s jauiniBjSojj' maasXa T/jMorrn 



kJ UJLXllk/Mk/ 



saoBjaa^uj jaXsq 
pire saririug luauiaSBUBp^; ^jo^a^ 

Z aranjOA 

aauajajay 

s^auiuiBjSojd oia^sAg X3N0CI0 

ajBAvyog uia^sXg asBg 

X aumjoA 

aauajaja^i 

s.aataraBoSojd aia^Sifg X3N0CI0 

3dusj3J8H imAO X3N0Q0 

sa3Bssap\[ opsouSBiQ X3N0(I0 

:(panin^uoo) spsmrejtf X3N0(I0 



T STBnUBJ\[ 
3UJIU0 



.raquiii^ 
uopBOixqnj 



9RIX IBnuBiM 



fri7mtiinin r \'i srcniroriT naimau 't-ct amnT 



sjBmrepf papjjay 



Related Manuals 



Table B-l. Related Manuals (Continued) 



Manual Title 


Publication 
Number 


Online 
Manuals 1 


Migration Manuals: 






Migration from IBM to NOS/VE 
Tutorial/Usage 


60489507 


MIGRATE. 
IBM 


Migration from NOS to NOS/VE 
Tutorial/Usage 


60489503 


MIGRATE. 
NOS 


Migration from NOS to NOS/VE 


60489504 





Standalone 
Tutorial/Usage 



Migration from NOS/BE to NOS/VE 


60489505 


MIGRATE. 


Tutorial/Usage 




NOSBE 


Migration from NOS/BE to NOS/VE 


60489506 




Standalone 






Tutorial/Usage 






Migration from VAX/VMS to NOS/VE 


60489508 


MIGRATE. 


Tutorial/Usage 




VAX 


Miscellaneous Manuals: 






Control Data CONNECT 


60462560 




User's Guide 






rVRTTIR /"Wiling T«vt t™. wnOrtTF 


an a qq a no 


ni^vrrTVtfvrri 


Usage 






CONTEXT 


60488419 




Summary CJard 







1. This column lists the title of the online version of the manual and 
indicates whether the examples in the printed manual are in the 
online Examples manual. 

(Continued) 
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8I-a siimuBui pa^Bjaa 



j uoisiAay 



(parmpuoj) 



IBTiireni saiduiBxg atiquo 

atf^ ut aiB panuBui pa^uud aq; ur sajdurexa aq:j aaq^aqAV sa^BDipui 

puB pntrera aq:j jo uoisaaA auquo a\# jo app aq^ s;stj nnm[OD siqj, x 





0Z,SSSW)9 


jCjopajtQ suoi^Boqddy 




02909^09 


bSbsq 
A^qpB^ }sojj a^ouiay 




«TQQQ*0Q 


A\iBuiumg 

3A/S0N 
joj luamuojiAug SunninBJSojj 

aSBSfi 


-NOHIANa 




3A/S0N 
jqj ^uauiuojiAug SuiuiuiBjSojd 


3A~SON 




uopBuuojui oia^s^g 3A/S0N 






a§BSfi 
saidniBX'? lA/cnw 


3A~1IVIM 




aSBSfi 

aA/iivw 




6TQfr9Kt9 


pjBQ AJBUIUITlg 

aA/iivw 


saovssaw 


SI9fr9W)9 


aSBsn 
3A/SON - I0 J sagBssap\[ o^souSbtq 


onaaa 




aouajajajj spmfr 
3A/S0N JOJ §nqaQ 




SIS88fr09 


aSBSfl 

3a/son j °j Sn q 9 a 

:(panuijuoQ) sp3nirepv[ snoauBnaosij\[ 


I sxBnirej\[ 
annuo 


aaqoiii^ 
uorjBoqqrid 


3 WX IBnnBM 



(panmjuon) stbtiubiat oaiBTaw 'i-a aiQB.T. 



spnuBjij pajBjay 



Related Manuals 



Table B-l. Related Manuals (Continued) 



Manual Title 



Publication Online 
Number Manuals 1 



Hardware Manuals; 

CYBER Installation Package (CIP) 60457180 

Handbook 

CYBER 170 Computer Systems 60459960 

Models 825, 835, and 855 
General Description 
Hardware Reference 

CYBER 170 Computer Systems, 60458100 

Models 815, 825, 835, 845, and 855 
CYBER 180 Models 810, 830, 835, 
840, 845, 850, 855, and 860 
Codes Booklet 

CYBER 170 Computer Systems, 60458110 

Models 815, 825, 835, 845, and 855 

CYBER 180 Models 810, 830, 835, 

840, 845, 850, 855, and 860 

Maintenance Register 

Codes Booklet 

Virtual State Volume II 60458890 

Hardware Reference 

7221-1 Intelligent Small 60461090 

Magnetic Tape Subsystem 

Reference 

7021-31/32 Advanced Ta^e Subsystem 60449600 
Reference 

HPA/VE User's Reference 60461930 
Subsystem Reference 

1. This column lists the title of the online version of the manual and 
indicates whether the examples in the printed manual are in the 
online Examples manual. 
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1-0 18S -lapwreqo j uotstAaa 



■qsm noA" sb -iajDBJBqo qosa jo uotiB^ajdja^ui aq; 

ainiap o^ %t asn otj aajj ajB noA" 'laAaMoq 'pasn ;ou si jtq ^souiqjaj aq:j 

qotqM m suorjBonddB uj s.ia?3BJBqo HOSV P-repuB^s aip A"pro idaooB 

suoiiiBDTTddB asaq; 'ajojajaqi sasodmd [Bpads aoj ^xq sn$ asn A"pBaj{B 

(s^uauiuojTAua aSBH§tJB{ 3uiuiiuBa§oad aq; pire 'a^itjiii 001VXVO 

"JLiaa 3l R *^nB n aiWXiaa 9 H? sb *P ns ) suorjBOiiddB uaaaas nnj 

9 *LL "^usrauojiAua SupjjOM. ^uaaana jiioa* in aiqBjjBAB si ;tq ^somyaj aq; 

;Bq; inBiaao aq 'sjapBjBqo HOSV" UOU l BU0 THPP B auijap o; ;ubm noA" jj 

saa^DBJBqD 83X l B uoriippB ire auijap 

o% pasn aq ostb ubo ;xq ^souiya^ aq; gA/SON "I '.^abmou oaaz sa*bm[b 

st %iq ^soiuqjaj jo q^qSia aq; 'saaipBJBqo nogv M d 9 lAq qoBa ui 

paiipsrif ^qSu 3jb s^xq i asaqj, "a^Aq ;iq=g xns ui epos HOSV +I°i"L n 033 

s^uasajdaj 3A/S0N '(LL6I-r£X ISNV) 1 3S JapBJBqo HOSV pJBpuBjs 

(ISNV) ewpisui spjBpuB^g [BuopB^ iiBDTjaiuv aq^ s^ioddns aA/SON 

"(l"0 9 l°i B: } °? -I3J3-I) 13S ja^aBJBqo HOSV 9t R S * S TI xipuadds siqj, 



Q }9g JL9%0TSJLBJ\C) 



Character Set 



Table C-l. ASCII Character Set 





Hexa- 








Decimal 


decimal 


Octal 


Graphic or 




Code 


Code 


Code 


Mnemonic 


Name or Meaning 


000 


00 


000 


NUL 


Null 


001 


01 


001 


SOH 


Start of heading 


002 


02 


002 


STX 


Start of text 


003 


03 


003 


ETX 


End of text 


004 


04 


004 


EOT 


End of transmission 


005 


05 


005 


ENQ 


Enquiry 


006 


06 


006 


ACK 


Acknowledge 


007 


07 


007 


BEL 


Bell 


008 


08 


010 


BS 


Backspace 


009 


09 


Oil 


HT 


Horizontal tabulation 


010 


0A 


012 


LF 


Line feed 


Oil 


OB 


013 


VT 


Vertical tabulation 


012 


OC 


014 


FF 


Form feed 


013 


OD 


015 


CR 


Carriage return 


014 


OE 


016 


SO 


Shift out 


015 


OF 


017 


SI 


Shift in 


016 


10 


020 


DLE 


Data link escape 


017 


11 


021 


DC1 


Device control 1 


018 


12 


022 


DC2 


Device control 2 


019 


13 


023 


DC3 


Device control 3 


020 


14 


024 


DC4 


Device control 4 


021 


15 


025 


NAK 


Negative acknowledge 


022 


16 


026 


SYN 


Synchronous idle 


023 


17 


027 


ETB 


End of transmission block 


024 


18 


030 


CAN 


Cancel 


025 


19 


031 


EM 


End of medium 


026 


1A 


032 


SUB 


Substitute 


027 


IB 


033 


ESC 


Escape 


028 


1C 


034 


FS 


File separator 


029 


ID 


035 


GS 


Group separator 


030 


IE 


036 


RS 


Record separator 


031 


IF 


037 


US 


Unit separator 


032 


20 


040 


SP 


Space 


033 


21 


041 


! 


Exclamation point 


034 


22 


042 


II 


Quotation marks 


035 


23 


043 


# 


Number sign 


036 


24 


044 


$ 


Dollar sign 


037 


25 


045 


% 


Percent sign 


038 


26 


046 


& 


Ampersand 


039 


27 


047 


' 


Apostrophe 



tL,ontinued) 
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s-o vs JwpBjBqo 



g uoisiAay 



(panui^uog) 



asBDjaddfi 





ill 


Af 


6£0 


il assaiaddft 


N 


911 


at 


8£0 


j^ asBDjaddrj 


M 


STI 


at 


££0 


1 asBDjaddfi 


1 


tTT 


at 


9£0 


3 asBaaaddf} 


H 


SIT 


at 


9£0 


p asBOjaddfj 


P 


SIT 


vt 


t£0 


I asssjaddf} 


I 


TIT 


6t 


810 


H asBDjaddfi 


H 


on 


8t 


SAO 


■0 asBDjaddfi 





£01 


£t 


T£0 


^ aseojaddfi 


d 


901 


9t 


QLO 


g asBaiaddrj 


a 


901 


St 


690 


q aseojaddfi 


a 


to I 


tt 


890 


q asBoaaddfi 





801 


8t 


£90 


a asBDjaddfi 


a 


SOT 


St 


990 


V asBDjaddfi 


V 


101 


It 


390 


IB iBtojauraioQ 


© 


001 


Ot 


t90 


5jjbui uorjsanft 


6 


££0 


as 


890 


uBq} aajBajf) 


< 


9£0 


as 


S90 


sjBtibg 


= 


S£0 


as 


190 


UBtfl ssaq 


> 


WO 


OS 


090 


uojooiiuag 


t 


8£0 


as 


690 


uoioQ 


: 


S£0 


vs 


890 


SU ?N 


6 


I£0 


68 


£90 


^8ia 


8 


02,0 


88 


990 


USABg 


£ 


£90 


£S 


930 


*!S 


9 


990 


98 


tso 


aAijj 


9 


990 


38 


830 


moj 


t 


WO 


ts 


SSO 


aajqj, 


8 


890 


SS 


TSO 


OJ&i 


S 


390 


ss 


OSO 


ano 


T 


190 


ts 


6t0 


ojaz 





090 


OS 


8t0 


■jubis 


/ 


£90 


as 


£t0 


pOU3£ 




990 


as 


9t0 


uaqdXj^ 


- 


930 


as 


sto 


BraraoQ 


* 


WO 


OS 


tto 


sntd 


+ 


890 


as 


sto 


2[sua)sv 


* 


S90 


vs 


sto 


sisaipuajBd Shisotq 


( 


ISO 


6S 


TtO 


sraoipmajBd Sumado 


) 


090 


8S 


oto 


Suiweaj/i jo anre^ 


aiuoiuauj\[ 


apoo 


apoo 


apoo 




jo aiqdBjg 


f*m>o 


Itjvupsp 
-Bxan 


[KIDKiaQ 



(penunuof)) jas jaiaBjBnr* rrrvav - T-r» araBT. 



%9Q ja^DBJB^Q 



Character Set 



Table C-l. ASCH Character Set (Continued) 





Hexa- 








Decimal 


decimal 


Octal 


Graphic or 




Code 


Code 


Code 


Mnemonic 


Name or Meaning 


080 


50 


120 


P 


Uppercase P 


081 


51 


121 


Q 


Uppercase Q 


082 


52 


122 


R 


Uppercase R 


083 


53 


123 


S 


Uppercase S 


084 


54 


124 


T 


Uppercase T 


085 


55 


125 


U 


Uppercase U 


086 


56 


126 


V 


Uppercase V 


087 


57 


127 


w 


Uppercase W 


088 


58 


130 


X 


Uppercase X 


089 


59 


131 


Y 


Uppercase Y 


090 


5A 


132 


z 


Uppercase Z 


091 


5B 


133 


[ 


Opening bracket 


092 


5C 


134 


\ 


Reverse slant 


093 


5D 


135 


] 


Closing bracket 


094 


5E 


136 


* 


Circumflex 


095 


5F 


137 


_ 


Underline 


096 


60 


140 


- 


Grave accent 


097 


61 


141 


a 


Lowercase a 


098 


62 


142 


b 


Lowercase b 


099 


63 


143 


c 


Lowercase c 


100 


64 


144 


d 


Lowercase d 


101 


65 


145 


e 


Lowercase e 


102 


66 


146 


f 


Lowercase f 


103 


67 


147 


g 


Lowercase g 


104 


68 


150 


h 


Lowercase h 


105 


69 


151 


i 


Lowercase i 


106 


6A 


152 


J 


Lowercase j 


107 


6B 


153 


k 


Lowercase k 


108 


6C 


154 


1 


Lowercase 1 


109 


6D 


155 


m 


Lowercase m 


110 


6E 


156 


n 


Lowercase n 


111 


6F 


157 





Lowercase o 


112 


70 


160 


P 


Lowercase p 


113 


71 


161 


q 


Lowercase q 


114 


72 


162 


r 


Lowercase r 


115 


73 


163 


s 


Lowercase s 


116 


74 


164 


t 


Lowercase t 


117 


75 


165 


u 


Lowercase u 


118 


76 


166 


V 


Lowercase v 


119 


77 


167 


w 


Lowercase w 



(Continued) 
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S-3 "laS -lapB-iBqo ^ uoisia»h 



snapci 


iaa 


ALT 


dl 


AST 


apni 


-M 


9AI 


3A 


9SX 


aoBjq Shisojq 


{ 


SAT 


cia 


SSI 


3UI{ [B0pj3jV 


i 


fLl 


DA 


m 


aaejq Smusdo 


} 


Zll 


9A 


821 


Z 8SBM3AiOq 


z 


SAT 


VA 


SZI 


a 1 asBaasM.oq 


K 


TAX 


6A 


1ST 


x asBOMMoq 


X 


Oil 


8A 


OZl 



guureaj^ jo aure^ oiuouiauj^ spo3 3 P°0 a P°0 

jo aiqdBjg ibjoq jBuipap [BonoeQ 
-Bxajj 



fratunino'Y) iac jaiaKjen^ tt^cw •t-'** siobt 



%SQ J*PBJBq3 



I-Q SpJOj^ p3AJ3SW{J 



j UOlSTAajJ 



aanaaooHd~o,i 


ivaa 


NOIXONfia 


~aaiNiod - 1 iaaAMO0# 


avaa 


dNaoNna 


dVMS~aavd]A[oo# 


HSild 


kddicLia 


ai~aanvo# 


wvaooaa 


aNaaoa 


ssanaav# 


aNaooad 


aoa 


J3HX 


aanaaooad 


xwa 


aox 


aaaa 


asiva 


loax 


dOd 


xixa 


3XIHM 


aaaovd 


(3N3 


aNaiiHM 


aao 


aiasis 


aiiHM 


ao 


3S13 


HVA 


NO 


X03f3 


amvAaaddn 


aaxixcno 


OXNMOd 


uNnoaaaddn 


aao 


oa 


ILLNfl 


ao 


Aia 


3dAl 


ION 


310A0 


snax 


aiidwoooN 


XSNOO 


01 


UN 


SlIdPMOO 


aixix 


xxsn 


XN3WJMO0 


N3HX 


aiiLLMaN 


aHO 


oons 


amaoK 


DVXHHO 


HxoNaiaxs 


aNaaow 


clllDMrxLJ 


dsaoNiaxs 


aom 


ONaaHo 


DNiaxs 


amvAaaMoa 


1INMH0 


OIXVXS 


aNnoaaaMOT 


iivaHO 


ONIOVdS 


raoxsn 


avHO 


dias 


xxaxsn 


TT30 


xas 


sxoxsn 


xvo 


©as 


nvxsn 


ONSSVO 


Noixoas 


xsn 


3SV0 


xHDia 


Aavaan 


aNnoa 


Nanxaa 


xaaa 


Nvaiooa 


dj&d.otd.ci 


aaoaiNi 


Nioaa 


xvaasa 


3NHNI 


Avaav 


daa 


NI 


onv 


laa 


ciNaai 


axvooiiv 


aaooaa 


ai 


aaNOnv 


aNaoaa 


dV3H 


svnv 


;xau pajsii ajB qigAO in spaoM psAjasaa aqj, 



a 



spao/vv p^Ajasa^f 



#FREE_ 


#PTR 


#SPOIL 


RUNNING. 


#PURGE_ 


#TRANSLATE 


CLOCK 


BUFFER 


#UNCHECKED_ 


#GATE 


#READ_ 


CONVERSION 


#HASH_SVA 


REGISTER 


#WRITE_REGISTER 


#INLINE 


#REL 


$CHAR 


#KEYPOINT 


#RING 


$INTEGER 


#LOC 


#SCAN 


$REAL 


#OFFSET 


#SEGMENT 




#PREVIOUS_ 


#SEQ 




SAVE_AREA 


#SIZE 
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X-a uorwuasaadaa b^bq j aoisiAajj 



•;iq ajqBjp3AB ;sjij aq; ui pajo;s aq ppiOM ;i suBaui ;iq ia;A*q 

a^qB^iBAB ;sjtj aq; ui paao;s aq ppiOM adA"; b;bp aq; subbui a^fq pjOM 

aqj, ajn;Dtu;s pa^oBd jo paijoBdun ub jo ;uauoduioo b si ;i ji pajo;s 

st adA; B;sp paijpads aq; A\oq a;Boipui suuuqoa oav; ;sbj aqj, Ajouiaui 

ut pa;uasajdaj ajB sadA"; B;sp ;uajajjip A\oq sazuBuiums x-g aiq^J, 

■(H^a b q;iA\ snouiAuouAs si a;Aq ;iq-8 ub) A"[;oaaip passaappB 

aq ubd spjOA\ pus sa;A"q q;og pjOM ;iq-^9 b o; sa;A"q 8 puB a;Aq b 

ckj s;iq 8 aaB ajaqj, ;iq b si gA/SON ™ Ajoutara jo ;iun ;saip3ius aqj, 

•adA"; pajn;oru;s jo ja;uiod xa[duioo aaoui b si ;i ji A^Bpadsa 

'guxsn ajB noX adA; JBpiDi;jBd aq; joj uoi;duosap aq; psaj ospa 

Pinoqs noA 'sbsbd ;soui joj LiB;ap ;uapiijns saAiS x-g ^iq^ H^noq^y 

•;uauiuBijB puB '3unioi;isod 'fkippBd ui suoi;buba q;iM. pajo;s 

si pjooaj b A\oq a;Bj;siqii sajduiBxa 'A^Butg -adA; qoBa joj uaAiS 

ajB suopdijosap paiiBjap 'ajqB; aq; Supftoijog - sadA; B;sp uomuioo 

'ajdinis aq; 'aouajajaj ipmb joj 'sazuBuiums x-g aiqBj, Ajouiara 

ui pajo;s ajB sadA; b;bp qiaAO 9X *°H saquosap xipuaddB siqj 



Table E-l. Data Representation in Memory 



Type 


Size 


Unpacked 
Alignment 


Packed 
Alignment 


integer 


8 bytes 


Byte 


Byte 


Character 


1 byte 


Byte 


Bit 


Boolean 


1 bit 


Right-justified 
in a byte 


Bit 


Ordinal 


As needed for 
components 


Right-justified 
in a byte 


Bit if ^ 57 
components; 
byte if > 57 
components 


Subrange 


As needed for 
components 


Right-justified 
in a byte 


Bit if =£ 57 
components; 
byte if > 57 
components 


Real 


8 bytes 


Byte 


Byte 


Cell 


Byte 


Byte 


Byte 


Fixed 
pointer 


6 bytes 


Byte 


Byte 


Fixed 

relative 
pointer 


4 bytes 


Byte 


Byte 


String 


1 byte for each 
character 


Byte 


Byte 


Array/ 
Record 


Depends on 
type of 
components 


Byte 


Components 
are unaligned 


Set 


As needed for 
components 


Right-justified 
in a byte 


Bit if ^ 57 
components; 
byte if > 57 
components 
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g-g uorve-juasajda'H ^WI d aoTSiAag 



S T anax J0 J P 3sn anjBA aq; to st asiva J0 J P ssn an^BA [Buja;ur aqj, 

•pau§TTB-;Tq st puB ;jq x pa;BD0jTB 

st adA"; uBajpoq paspsd y pauSTTB-aiAq st puB aiiAq i pa;BDOjiB st adA"; 

uBajooq paTjDBdun ub 'ajn;onj;s b urq;T^ pjoav b ut paTjr;snf-;qgTJ 

pUB pailgflB-^Aq ST ;T ty/Lq l p9^B0O[IB ST ajqBTJBA OB3[00q y 

nt^joog 

paU§TTB-;Tq ST ddn.% JS^SBJBqO p33[3Bd B ;p9tImiB-»:iA"q Si adA; 

ja^DBJBqo pespBchm ub 'ajn;3ru;s b uTq;T$V •pjom b jo a;Aq ;soui;q3u 
aq; uo pau§Tp3 st puB s;jq 8 pa;BDOijB st ajqBUBA ja;DBJBqo y 

pajpBdun jo paspBd 

st ajn;otu;s aq; jaq;aqM jo ssajpjBSaj anj; st sjq; !AjBpunoq 9\K<\ b 

ttq riatT^TT-g ct sjivonj^s b tn TT ' | TA*. ^ixsuoduioD acLC^-jaBa^ui u t - t 'AjBpuno^ 

pjom b uo pauSTjB st puB s;jq fg pa;BooijB st a^qBUBA jaSa;uT uy 

AjBpunoq 

a;Aq b up paulftTB st a<M; aq; suBara pau3Tp3-a;Aq 'asT^a^i iAjBpunoq 

pjOM b uo pauS^B st adA; aq; subbui pauifrp3-pjOAi asBjqd aqj, 

(ajTvpru;s jaq;ouB ujq;TAi aq 

ubo jo) ajn;onj;s jaq;ouB urq;TM jras;T st qorqAV adA; ;sq; jo ;uauodiuoo 

b o; Apio sajTddB uopduosap aq; 'asTAuaq;Q 'A{TBOTjpads 1 BI W sb;b;s 

it 'adA; uaAtS aq; jo aiqBUBA b o; saTiddB uorjduDsap aq; ji a;Aq b 

uo pau§Tp3 st pjoaaj b unflTM st puB adA; jaSa;ur jo aq o; pajBpap st 

;Bq; pray b ;ng AjBpunoq pjOM b uo pauS^B st jaSaun ub sb pajBpap 

st ;sq; a^qBTJBA B 'axduiBxa jg^ (8*qBpBA pjos-aj b inq;TM pray b sb 

qons) ajn;oTu;s b mq;TiA ;uauoduioo b jo adA; aq; jo (ijas;T Aq spuBis 

qaniift) ajciBTJBA pajBpap b jo adA; aq; st ;t jaq;aqM uo Smpuadap 

jajjrp Abbj adA; aq; jo ;uauiu§Tp3 aq; 'mo^oj ;Bq; suopduosap aq; uj 

sacLCj. bjbq TffTAO 



CYBIL Data Types 

Ordinals 

An ordinal type is treated as a subrange type from through the 
total number of elements minus 1 (that is, 0..n-l where n represents 
the total number of elements in the ordinal). For further information, 
refer to the description of subranges. 

Subranges 

A subrange variable is allocated 8 bytes if its lower bound is 
negative. If its lower bound is or positive, it is allocated from 1 to 
8 bytes, depending on the value of the upper bound. It is byte-aligned 
on the rightmost byte of a word. 

Within a structure, an unpacked subrange type is allocated the same 
as a subrange variable; however, it need not be aligned on the 
rightmost byte of a word although it is byte-aligned. 

A packed subrange type is allocated enough memory to hold the 
subrange in bits. The exact length can be calculated using the 
following formula. This formula assumes the range is given as A..B 
(that is, A is the lower bound and B is the upper bound). 

If A & 0, LENGTH = CEILING (LOG2 (B + l) ) 

If A < 0, LENGTH = 1 + CEILING (LOG2 (MAX (ABS(A), 
B + l) ) ) 

A packed subrange type is bit-aligned if it contains 57 or less 
components; it is byte-aligned if it contains more than 57 components. 

The maximum integer subrange is -7FFFFFFFFFFFFFFF 
hexadecimal through 7FFFFFFFFFFFFFFF hexadecimal. 

Reals 

A real variable is allocated 64 bits and is word-aligned. Within a 
structure, a real type is byte-aligned; this is true regardless of 
whether the structure is packed or unpacked. 

Cells 

A cell type is allocated 1 byte and is byte-aligned. 
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g.g uorjB^uasajday wjbq j uotstas^ 



pauipapBxaq 00000008 

01 jaqutnu aijAq atpj pire 'psuipapBxaq j^o °3 -laquinu ^uauiSas 

aq:j 'psrapapBxaq jo °^ ^ 9S S T .raqranu Sup aq:j 'ssaappB ibiujia 

ssaooad b joj jaipsa ujwoqs ibuuoj pjooaj aq^ Suisn 'spjOM aaq^o u\ 

[(9i)ooooooo8 'OOdddO 'ODdO] = : ss3baav~nvniaiA"ss33oyd hin 

:smo[ioj sb pauijap si ^ub^suoo jajupd qj^ aqj, 

}us?suoq a^uiod iim 

pa:spBduri jo pa^osd si ajmoru^s aq; jraq^aqjA jo ssajpjtBSaa 

bjxj% si snp !pauSi^B-a^q si ad/L% ja^uiod b 'aan^onj^s b unpiM. pjOM 

b ui paiji}sn{4qgTj si sa^q g UBq^ ssa[ jo ajqBiiBA ja^uiod y yaj aq$ 

uo pau3qB-pjOM si sa^Aq ojoui jo 8 saidnDDO ^Bq? ajqBUBA ja^uiod y 

VAd 3l W SMO Il°J ^i^Bipauiuii jajduosap aqj, (ja^B| 
oaauosao^ aoafao aiaBidBDB am ioi loadiiDsao b dub va,i am stiiBiuoa 

L l a L / ' • L LI' L I > U ' • L L ¥ X 1U. L ' » ' 

azis ajqe^dspB ub q^iM pafqo tre o% ja^uiod y uoipas siq; ui ja^Bj 

paqijasap si qoiqAv aouanbas b <y\ ja^uiod b si uotjdaoxa a^Suis aq^ 'yAd 

aqi X[uo suib^uoo azis paxij b q^iM :pafqo ub oq. ua^utod b 'A^iBjauaQ 

; (9L)d=ld=ldddZ •• (91)00000008- = a3931NI~d1VH 

'si ^Bq; ^BurpapBxaq ^s^ga^a qSnooqi p3rapapBxaq 
00000008- m0 *} 3§uBaqns aqi sb pauijap si HaOaiNI""daVH 

: 0N333H 

(pauSlS 'S^iq %£) 'H3931NI~d~lVH : H3awriN~3±A9 

(pauSisun 's;iq z\) 'S60fr " : a3aHnN~lN3W93S 

(pauSxsxiR 's^iq f) 'sl •• o : y3awnN~DNia 

aaoosb asxovd = ss3aaav"nvniaiA"ss330Wd 

:^BUiaoj giqMonqj aq$ SBq ;i -pauSips-e^Aq saba^b si %wqi (yAd) ssaapp-B 

{BtvpiA ssaoojd a^q-9 b st la^uiod aq^ jo p^aii ssaappB aqj, papqo 

aq^ aquDsap or\ papaau si ^Bq^ uopBuuojin a*ub siqd 's^utod %i qoiqM 

oq. qoafqo aqq jo aqAq qs.ni aq^ jo ssajpps aq^ jo pasodmos si aa^uiod y 



CYBIL Data Types 

Adaptable Pointers 

The descriptors for adaptable objects of pointers are byte-aligned and 
have the following formats for adaptable strings, arrays, sequences, 
user heaps, and records. 

• An adaptable string descriptor is a 2-byte field with the following 
format: 

ADAPTABLE STRING SIZE: 65535 

This field indicates the length of the string in bytes. The length 
can be in the range of through 65,535. 



• 



An adaptable array descriptor is a 1 2-byte record with the 
following format: 

ARRAY_DESCRIPTOR = RECORD 

array.SIZE: HALF.INTEGER, (in bits or bytes) 
LOWER_BOUND: HALF. INTEGER, 

element_size : HALF.INTEGER, (in bits or bytes) 

RECEND; 

When the array is unpacked, the ARRAY_SIZE and ELEMENT- 
SIZE fields are both in bytes. When the array is packed, they are 
both in bits. 
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£-51 aopBjaasaaday bjbq j uoi8iA»y 



•(sadA> 

ajqB^dBpB joj paquDsap A"TsnoiAajd sb) paooaj aq:} urq^iiA pray 

aiaBidBBB am 10 loiduosao am sx joiduasai) djqdsj araBidBOB uv 

sa^q ui ajmooris aq^ jo qiiBuaj umuirxBui aq:i saiiBDipui piati siqj, 

: a3931NI~d1VH : 3zis~dV3H~a3sn"3navidvav 

:;buijoj SuiAMqjqj 
aq^ q^TM Pl^y 3 ^ < \-f B S T •lajduasap dBaq jasn a^qB^dBpB uy 

aouanbas paxti b 01 aa^tnod b joj sb auiBS aq^ si ibulioj stqj, 

aouanbas 

aq^ ui uopBocq ajqBTTBAB ;xau aq^ o\ ^asjjo ub si piaii aiHVlIVAV 

aqj, aouanbas aq} jo doq. aq; cq lasjjo ub st piati jjj^n aqj, 

; on ao ay 
"a393iNi"dnvH : 3ianivAV 

*a393lNI~d1VH : iiwn 

'ss3aaav~ivniaiA~ss330bd : 33N3fi03S~a3iNiod 

aa033a = a31NIOd~33N3n03S 

::ibuuoi Sutavoiioj aq; q^iAV paooaj 
aoAq-^T b si lajuiod sii qiiAv joaduasap aouanbas aiqBadBPB uy 

sadiCx bibq 1ISAO 



CYBIL Data Types 

Pointers to Sequences 

A pointer to a sequence is a 14-byte record with the following format: 

SEQUENCE_POINTER = RECORD 

POINTER_SEQUENCE : PROCESS_VIRTUAL_ADDRESS, 

LIMIT: HALF.INTEGER, 

AVAILABLE: HALF_INTEGER, 
RECEND; 

The LIMIT field is an offset to the top of the sequence. The 
AVAILABLE field is an offset to the next available location in the 
sequence. 

This format is the same as for a pointer to an adaptable sequence. 

Pointers to Bound Variant Records 

A pointer to a bound variant record consists of a 6-byte PVA, followed 
by a 4-byte size descriptor with the following format: 

BOUND_VARI ANT_RECORD_SIZE : HALF_INTEGER ; 
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g-a uorronasajdaH b?bq j noistnay 



JOXia 

ub sb la^uiod aanpaaojd qj^j b qgno-api ipso b sajpireq yem ajnpaooad 

AjBjqij amp-uoipioaxa ub 03 s^uiod acxjdiJDsap ajnpaooad "-jjjsj aq:j aaaqav 

: [niN'yoidia3S3a 

"3«na3D0bd _ niN~01~a31NI0d] =•■ a3J.NIOd~30ad : a31NIOd~30ad~-|IN 

:smoi[oj sb pauijap si jubisuos ja^uiod aonpaaoad 

UN 3 MiL s^jom sjCbm[B uosixeduioa ja^utod %tbi\% saonsua snjj, 

•pBa^sut pasn si ja^utod ajnpaoo.nl ^^N aq:j 'ajojaaaq; 'puB jjuij di^bjs b 

ajinbaj ;ou saop a^npora b jo [aAaj ?soraja;no aq^ ya paaBpap ajnpaooad 

y "^ax\ oijb^s aqi si ja^uiod aanpaooid aq^ ui pjaij puooas aqj, 

•jbiuibui aauaaajai ajBMpasq a^s pan^JtA aq:j jo n auiiqoA 

o; aajaj 'uoipas Suiptnq aq^ puB sja^uiod asaqj ;noqB uopBuziojui 

jaq^jty: jo^ ua^uiod uopoas Suipuiq b puB la^uiod asBq apoo b 

:sp[aij OAiq. jo s^stsuoo jo^diJDsap srqj, uotpas Suipuiq aq^ ui jo^dijasap 

ajnpaoojd aq; oj ja^uiod b si ja^uiod aonpaooid aq^ ui pjaij }sjtj aqj, 

: (JN 30 3d 
' ss3aaav~-ivnj.yiA~ss33oad : iiN~acmNi-r3iiv±s 
' sS3baav~nvniaiA"ss33oad : aoidia3S3a _ 3ana33oad~oi~a3iNiOd 

aaossa = a3iNiOd"3oad 

:;Btaaoj 
SuiMojpj aq; q;iM pjooaa a^A*q-gx « si aanpaaoad b «j. ja^uiod y 



sadiCx kjbq iiaAO 



CYBIL Data Types 

Relative Pointers 

A relative pointer is a 4-byte field with the following format: 

RELATIVE.ADDRESS = .. OFFFFFFFF( 16) ; 

This field gives the byte offset of the object field from the start of the 
parent variable. This relative address can be in the range of 
through OFFFFFFFF hexadecimal. 

A relative pointer is byte-aligned. 

Adaptable Relative Pointers 

A relative pointer to an adaptable type object is the 4-byte relative 
address plus a descriptor for the adaptable object. This descriptor 
immediately follows the relative address field. Descriptors for 
adaptable relative pointer types have the same alignment and formats 
as described previously under Adaptable Pointers. 

Relative Pointers to Sequences 

A relative pointer to a sequence is a 12-byte record with the following 
format: 

RELATIVE_POINTER_TO_SEQUENCE = RECORD 

RELATIVE.POINTER : RELATIVE_ADDRESS , 

LIMIT: HALF_INTEGER, 

AVAILABLE : HALF_INTEGER , 
RECEND; 

This format is the same for both fixed and adaptable sequences. 

Relative Pointers to Bound Variant Records 

A relative pointer to a bound variant record is the 4-byte relative 
address followed by a 4-byte size descriptor with the following format: 

BOUND_VARIANT_RECORD_SIZE : HALF_INTEGER; 
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jj-jj uor}Biuss3jd3H bjbq j uoistAay 



uoi:}B.iBpap pjOD3J aq} 

ui (asBq GOW l as JJ° Q3NDnV) -ta^aiHBJBd iu9inu§ip3 ST P U T P9UT D9( is 

asBq eq^ jo 9idtqnui b si spaoaaa pauSqB jo abjjb ub jo azis aqj, 

UBmpapBxaq j^jijMddi, ' S T 1 B H1) luautSas 

B JO 3ZIS 3tp SI ABJJB UB JO 3ZIS UIIUUIXBUI 3q^ ! J9A9AV0H AJOUI9UI 

jo A";qiqB{iBAB gq; Aq A"nio painnij si abjjb ub jo azis aq^ 'jBjauag u\ 

•sa^q jo jaqumu pjjlaiun ub saidnoDO %i 'pauSi^e-e^q 

si abjjb 9q; jo adA} ^uauoduioo aq? ji s^iq ^g uBq^ j9Sjbi si abjjb aq; 

ji jo 'AjBpunoq a^Cq b uo ^jb^s ifyBuuou ppio/A s^uauiaja ^uauoduioo s^i 

jo 9d/q aq} ji AjBpunoq a^Aq b uo pauSqB si jps^i abjjb aqj, pau£iip3 

;ou 9jb s^uauiap s^i %nq A[JBinHis pa^BDO^B si adA} abjjb paspBd y 

•pauSip SABjyqB bjb s^uaraaja s^i puB ajqBiJBA abjjb ub 
sb 9uibs aq; pg^BOonB si adA> abjjb pa^DBdun ub 'ajn^oru^s b uiq^i/^ 

yai aq* uo 

pauSqB-pjOM si afqBiJBA abjjb aqj, acLfy ;uauoduioD ^Bq^ o% BuipjoooB 

^uaraaia qDBa joj pa^Boo^B aoBds q^im adX^ ^uauoduioD s ( a"bjjb 

aq^ jo s;u9ui9[9 jo ^si[ snorispuoo b sb ps^Baai si ajqBTJBA abjjb uy 

ggg'gg si Suij;s b ui paAwqp3 sjapBJBqo jo jaqumu umunxBui aqj, 

p9T[DBdun jo pasfOBd si ajnpiu+s aq+ jaq^aqM jo ssajpjBSaa 
atu^ si siq^ tpauSifB-g^Aq si acLfy Suia^s b 'ajnipru^s b un#i^ 

■+q§iJ aq$ uo 

pauSip3-paoM si %i 'sa^Xq g usq; ssaj si ^i ji "ip\ aqi uo pau3ip3-pjOM 

si ^i 'sa^Aq ajoui jo 8 saidiiDoo ajqBUBA aq; ji Suu^s aq? ui sjg^oBJBqo 

ajB ajaq^ sb sa^Xq jo jaqumu aures aq; pa^BDO^B si a^qBUBA Suijijs y 

sSnuig 

sacUx wbq 1ISAO 



CYBIL Data Types 

Records 

A record variable is treated as a contiguous list of the record fields 
and is allocated space according to the types of those individual fields. 
If it occupies more than one word, it is word-aligned on the left in 
the first word; a record that occupies less than one word is 
word-aligned on the right. 

An unpacked record type is allocated space the same as a record 
variable and its fields are aligned. The record itself is aligned on the 
boundary of the maximum alignment of any of its fields. For example, 
if one field has an alignment of MOD 8 1 and another field has an 
alignment of MOD 16, the alignment with the larger base (0 MOD 
16) is applied to the entire record; it is aligned on an even word 
boundary. 

A packed record type is allocated similarly but its fields are not 
aligned. Like an unpacked record type, the record itself is aligned on 
the maximum alignment of its fields. However, if the record is more 
than 57 bits, it must be byte-aligned at least. 

The length of a packed record depends on the length and alignment of 
its fields. The way a packed record is used (for example, as a record 
variable by itself, as a field in a larger record, or as an element of an 
array) does not affect how it is represented in memory. Thus, all 
occurrences of a packed record have the same length and alignment 
regardless of how it is used. 



1. Record alignment parameters are described under Records in chapter 4. 

E-12 CYBIL Language Definition Revision F 

W | 01/22/87 19:59:24 | 02/13/87 09:46:31 | 87/03/25 22.17.32 | 60464113 F | DATA REPRESENTATION | DRAFT COPY 



gl-g; uorjBiuasajcIag b^bq jf notsiAag 



pauijapun si s;iq pasnun aq; 10 juajuoo aqj, ;sjij sauioo jaAaqoiqM 

'pjaij ;xau aq; en jo AJBpunoq a;Aq ;xau aq; o; piredxa ubo s;uauiaja 

2,g uBq; aioui suib;uoo ;Bq; ;as y pjooaj aq; jo pjaij pasn ;xau 

aq; o; puBdxa ubd ;i jt A"{uo ;nq 's;iq £2 °% dn pxredxa ubo s;uauia[a 

2,3 ireq; ssaj suib;uoo ;Bq; adA"; ;as y s%i<\ gg o; dn pusdxa ubo spjaij 

adA; afuBjqns pus 'pauipjo 'uBajooq 'ja;0BJBq3 'Piaij ;xau aq; o; dn 

ajqissod sb s;iq aubui sb apnpm o; paSjBjua aq ubd p^aij ajqBpuBdxa 
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CYBIL Data Types 

Sets 

A set is represented by enough contiguous bits to hold the total 
number of elements in the set's type. The leftmost bit corresponds to 
the first element of the set's type, the next bit corresponds to the 
second element, and so on. 

A set variable is allocated a field of enough bytes to contain all the 
set's elements. If the field fits in a word, it is word-aligned on the 
right; otherwise, it is word-aligned on the left. 

Within a structure, an unpacked set type is allocated the same as a 
set variable. The field allocated is byte-aligned. 

A packed set type that contains more than 57 elements is treated as 
an unpacked set type. A packed set type that contains 57 or less 
elements is allocated a field with the number of bits (rather than 
bytes) necessary to hold the elements of the set. This field is 
bit-aligned. 

When the field is allocated in bytes rather than bits, the field may be 
larger than is necessary to hold the total number of elements in the 
base type of the set. In this case, the elements are right-justified in 
the field and unused bits to the left of the elements are set to 0. 

The maximum number of elements allowed in a set is 32,767. 
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Examples 

Examples 

The following examples show how a record would look in memory in 
various formats: first unpacked, then packed, packed with some 
positioning changes, and finally aligned. The memory shown here is in 
8-byte words, but because bytes can be addressed individually, it's 
possible the record could start at any byte (if it is not aligned 
otherwise). 

The unpacked record is: 

TYPE 
table = record 

name: string(7), 

fjle: (bi, di , lg, pr), 

number_of _accesses : integer, 

users: .. 100, 

ptr_iotype: "iotype, 

b: boolean, 
recend; 

This record would appear in memory as follows (slashes indicate 
unused memory): 



FILE 
Byte Byte 1 Byte 2 Byte 3 Byte 4 Byte 5 Byte 6 Byte 7 



NAME 
Character Character Character Character I Character Character Character 




I 



NUMBER OF ACCESSES 



ffi. 



yjuocna 



'2L 



PTR IOTYPE 



V//AA 

////A B 



!NQ1: 86/07/10 

The packed record is: 



TYPE 
table = packed record 
name: strlng(7), 
file: (bi, di, lg, pr), 
number_of .accesses : integer, 
users: .. 100, 
ptr_iotype: "iotype, 
b: boolean, 
recend ; 



E-16 CYBIL Language Definition Revision F 

W | 01/2Z/87 19:53:24 | 02/13/87 09:46:31 | 87/03/25 22. 17.32 | 60464113 F | DATA REPRESENTATION | DRAFT COPY 



£X-g uoflB^uasajday b^bq 



j uoisiAay 



Ol/ZO/98 : "SW 




3dAJLOI aid 



saasn 



S3SS303V jo aaawnN 




^ 



J813CJEU0 jaiaejeqo jsioejeqo | jawejetQ je»Mueio jmobjbio jswejeqo 
3WVN 



£ aiAg \ 9 aiAg g aiAg friiAg g aiAg 2 aiAg [ aiAg o^3~ 
31ld-i 



:(A\iouiaui pasnun 
a^Botpui saqsBjs) saio^oj sb £iouiaui ut jBadds pynoM pioaaa snjj, 



: puaoa j 

'adAjOL. :adA;oi~Ji.d 

'ueaiooq :q 

'ooi "" o =sjasn 

' J36a iu l : sassaoac - jo~ jaquinu 

'(Jd *Bl 'LP 'LQ) =31M 

'(i)BuLj;s -aureu 

pjooaj pa>)OBd = aiqei 

3dAI 

:aoBds aip jo asn luapijja 
ajora aifBui o; A^qSTTS paSuBjaBaa avou si 'smoiioj sb 'pjooaj aqj, 

Ot/iO/98 : S0N 



Oyy/, 


a 


1 1 1- 1 1 

3dAJLOI aid 


P 


suasn 




! ! ! ! ! 

S3SS333V jo aaawinN 




Hj> 


JW3BJBH0 Jaisejeqo jajoejeqo | jeioeietQ jajsejeiQ javwjeiQ isnoeietQ 



£ si Ag V 
31 Id -J 



9 aiAg g aiAg p aiAg g aiAg ? aiAg l aiAg o a**a 



:(A\iouiaui pasnun 
aiBarpui sausBTSI smottoi sb Aiouiatu ut jBaddB oraoM Daoaaj stu.t. 



saicfarexg 



Examples 

The following record declares the pointer field to be aligned at byte 
zero (the first byte) of a word: 



TYPE 
table = packed record 

name: string(7), 

file: (bi, di, lg, pr), 

number_of .accesses : i nt eger , 

users: .. 100, 

b: boolean, 

ptr_iotype: ALIGNED [0 MOD 83 'iotype, 
recend; 

This record would appear in memory as follows (slashes indicate 
unused memory): 



FILE 
Byte Byte 1 Byte 2 Byte 3 Byte 4 Byte 5 Byte 6 \ Byte 7 



I 



NAME 

Character Character Character Character I Character Character Character 



NUMBER OF ACCESSES 
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Stack Frame Mechanism 

In addition, each time a new procedure is called, the environment of 
the calling procedure is saved in a part of the stack frame called the 
save area (or the stack frame save area). This save area contains all 
the information necessary to resume execution of the calling procedure 
when the called procedure completes. 
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Various pointers in the stack frames link calling and called 
procedures, enclosed and enclosing procedures, the current stack frame 
and the next space available. (These pointers are controlled by the 
system, not the program.) 

The following example illustrates the process. Consider program A 
which has two sets of nested procedures: B and C, and D. 



Procedure A 



Procedure B 



Procedure C 



Call to procedure D 



Call to Drocedure C 



Procedure D 



Call to procedure B 



IPR0C1: 86/07/10 
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Stack Frame Mechanism 

A pointer called a static link (SL) is created that points back to the 
stack frame for A. A static link always points to the stack frame of 
the procedure containing the called procedure (and, in this case, A 
contains B) if the called procedure is an internal procedure of the 
calling procedure; otherwise, it is meaningless. The static link enables 
the most recently called procedure to have access to the variables 
already declared in the procedures that contain it. 

A dynamic link pointer is also created that points to A's stack frame. 
This dynamic pointer is called the previous save area (PSA) pointer, 
and it points to the area that was saved (that is, the environment) for 
the previous procedure, A. This pointer allows the environment of the 
preceding procedure (the calling procedure) to be restored when the 
current procedure (the called procedure) completes. 

The current stack frame pointer is updated automatically to the start 
of the current stack frame (the stack frame for procedure B) and the 
dynamic space pointer moves to the next available space in the stack. 

The call to procedure C results in a similar structure. Again the 
static and dynamic links point to the previous stack frames. 
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Stack Frame Mechanism 

The remainder of this section gives a more detailed description of the 
format and contents of a stack frame. 

The stack frame always consists of at least two parts: a fixed-size part 
and a variable-size part. The fixed-size part contains all the data 
whose size is known at compilation time and it includes the automatic 
variables for the procedure. The variable-size part contains all the 
adaptable structures whose sizes can be determined only at execution 
time. In addition, when one procedure calls another, the environment 
of the first is saved in its stack frame save area. For example, the 
stack initially appears as follows. 
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1STK3: 86/08/15 

After a call is made to a second procedure, the stack contains two 
frames as shown below. 
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Stack Frame Mechanism 



Stack Frame Save Area 

The hardware call instruction saves a designated set of registers in 
the save area, which can be thought of as the top of the rest of the 
stack frame of the procedure that issued the call. The stack frame of 
the called procedure is then built above the save area of the calling 
procedure. 

The save area can be broken down into two areas: the minimum save 
area and the maximum save area. 
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(Current Stack Frame Pointer) 


2 




User Mask 


A2 Register 

(Previous Save Area Pointer) 


3 




20 
28 
30 
38 
40 

80 
88 

100 




A3 Register 

(Binding Section Pointer) 


4 


Maximum 

Save 

Area 




A4 Register 
(Argument Pointer) 


5 




A5 Register 


6 






A6 Register 


7 






A7 Register 

• 

AF Register 


8 






16 






<0 Register 

• 

• 
<F Register 


17 
32 




•\C\ . 












*-oj 


STKSAV: 8 


3/08/08 







The minimum save area contains the P, A0, Al, and A2 registers, the 
stack frame descriptor, and the user mask. The maximum save area 
contains everything in the minimum save area plus, optionally, 
registers A3 through AF and registers X0 through XF. The contents 
of these registers is given later in this section. The CYBIL System 
Interface manual contains additional information on the stack frame 
save area. 
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6-ji ^uauraoiTAug aunx-uny H3A0 3I LL 



jj uoisiAay 



(AJBSS3DDU Jj) 

6o|Ojd i 
9m Aq dn jag 



eajB Ae|ds;p 

s ajnpaoojd Guinea 

gq}. tuoij psidoo 



80/90/98 : SI(mS 



JSiuiod ;si| juaain6jv 



ajnpaaojd 
(1,-U) |9A3| ;ua4jno jo JSO 



ajnpaoojd 



ojnpaaojd 
I |3Aa| iuajjno jo jsO 



ajnpaaojd 
|3Aa| ;ua.uno jo jso 



:;buijoj StnAvoqqj am ssq bbjb ABjdsip aqj, 

sa.mpaao.id jJurpaoaad aq; jo sajqBiJBA aq; ssaooB 0; 

ajnpaoojd ^xiajjno aq; joj ajqissod ;t ajjBui sja;uiod asaqj, aanpaooad 

;ua.uno aq; uib;uo3 ;Bq; sa.mpaao.id aq; i\e jo sauiBJj jjob^s aq; 

(B3jb AB{dsip aq; SutMonoj paquosap osjb) b;bp aanpaooad pa;jossy • 

(Mojaq [re;ap 
ui tt&oqs st BajB ABjdsip aq;) saanpaoojd SurpaDajd jo sajqBiiBA 
aq; ssaaoB 0; AjBssaoau uot;Bui.iojtn aq; Sinurajuoo b3jb ABjdstp y « 

;xxa ^booiuou b SBq uorpunj 
b uaqM BajB 3abs ;msaj uoppunj aq; sb pasn aq 0; pjOAi y • 

SuiipuBq uoi;ipuoo joj pjatj pazriBT;iui 'a^tq-8 uy « 

:suib;uod aniBjj 5ps;s aq; jo ;jBd azis-paxr; aqj, 

UBJ 3ZI«-P9XI>r 



rasureipaj^ aatBj^ jpKig 



Stack Frame Mechanism 

Each display area entry is a 6-byte pointer (a current stack frame 
pointer) that is right-justified in its display word. The total size of the 
display for a specific procedure is based on that procedure's nesting 
level. The prolog 1 will save the static link (if it was passed in register 
A5) only if the procedure was nested. The prolog will also save the 
parameter list pointer (if it was passed in register A4) only if the 
procedure contains at least one locally defined procedure. 

Automatic variables or value parameters may be declared so that all 
bounds and size information is known at compilation time. In this 
case, the fixed amount of storage that is required for the variable is 
allocated from the fixed bound part of the automatic stack. 

Adaptable parameters may be declared so that some bounds and size 
information is not known at compilation time. In this case, a type 
descriptor must be allocated for the type, containing the result of the 
calculation of all variable bounds and a variable descriptor that can 
locate the base address of the variable bound part of the automatic 
stack. These descriptors are allocated in the fixed bound part of the 
automatic stack. In addition, a workspace may be required in the 
fixed-size part to hold intermediate results for execution-time 
descriptor calculations. 



1. A prolog is a set of one or more instructions that is executed at the beginning of 
every procedure and function to set up the registers properly for that procedure or 
function. 
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tl-j luauiuojiAug aimx-un^ tjhao aqj, & uotsiAay 



;jBd azis-paxij aq; ui paure;uo3 9jb 
sgjqBUBA 9saq; joj sjo;diJDsap sqj, sun; uotpqiduioo ;b pauiuija;ap aq 

;OUUBD UOi;BOJOIIIT. 3ZTS pUB SpUtlOq 3S0qM SJa;9UIBJBd 9HTBA 9jqB;clBpB 

\[B joj 9§bjo;s sutbjuod auiBJj ipB;s aq; jo ;jBd azis-ajqBUBA aqj, 

^jbj azig-aiqewBA 

■aim; uoi;Biiduioo ;b pauraua^ap 

aq ubo aoBds3{jOM stq; jo azrs aqj, uoi;tioaxa Suunp pa;dui33jd 

ajB ;Bq; saa^sxSaa ajBAqxreq sure;u03 bbjb AlOTjjaAO ja;siSaj aqj, 

uopoas spq; in ja;Bj uaAtg 

si sja^auiBJBd guisssd uo uoi;buuojui iaq;jn^ (AJBSsaoau jt jG;diJ3sap 

b stqd) saa;uiod 9;A"q-9 Aq pa;uasajdaj bjb sja;attiBJBd jaq;o i\y 

•atqBA aq; pjpq o; pajtnbaa s9;Aq jo jgqumu ;sajp3uis 9q; ui atqBA s;i 

Aq ;si| aq; ui pa;uas3jdaj si j3;auiBJBd aq; 'sa;Aq g o; jBnba jo uBq; 

ssaj si q^ua^ ja;auiBJBd tbiujoj s;i pus atqBA Aq passBd si ja;auiBJBd 

aq; jj j9;mod b jo atqBA b jaq;ia sb ;sq ja;auiBJBd aq; ui pa;uasajdaj 

si ja;auiBjBd jbii;ob qoBg bqjb ;xed paxri ua\o s;i ui pa;BoonB 9q 

;snui ;sq ja;aurejBd aq; 'sajnpaDOjd jaq;o sjtbo ajtipgDOjd ;uajjna aq; 

IT B9JB 9ZIS-D9XII B UI DT3U 3JB STIBO ajtlOaDOJd JOI S1SIT J3iaiIIBJBd 3U.T. 



uisiHBtpay^ aurBj^ sp^ig 



Register Assignments 

Register Assignments 

While a CYBIL program is executing, the following registers are 
assigned: 

Register 

(Hexadecimal) Contents 

AO Dynamic space pointer (DSP) 

Al Current stack frame pointer (CSF) 

A2 Previous save area pointer (PSA) 

A3 Binding section pointer (BSP) 

A4 Argument list pointer (ALP) 

A5 Static link (SL) 

AA through AE and Parameters passed to internal procedures or 
X9 through XD functions 

XO Number of parameters passed (in bits 40 

through 43) 

XE Line number for range checking (LN) 

AF Function result (if it is a simple pointer) 

XF Function result (if it is scalar) 

The dynamic space pointer, current stack frame r K>inter Tevious save 
area pointer, and static link are described earlier. The binding section 
pointer indicates the binding section of the procedure that is currently 
executing. The argument list pointer points to the parameter list 
passed by the caiiing procedure. 
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ex-j luarauojiAua auiii-xma qigAO aqi ,£ uoisiAay 



T 



■jaq.aure.iBu. [bti;db ;sjy aq; 

saijpgds '9sbo siq; ui ';sq j9;9uiBJBd aq; jo ;uama[a puooas aqj, - ;sq 

ja;aurejBd aq; jo ;u9ui9ia ;sjij aq; sb paiji;sii£-;jaT_ paao;s si ;t 'sacLC; 

asaq; jo 9uo ;ou si ;ps9J uotpunj aq; jj ojaz q;iM panu *re s;iq 

pasmm A"uy 'ja;si§9J jjx aq; ui iqSiJ 9q; uo pauSijB p9uan;aj si ;i 

'siiq f?9 o; jBiiba jo ueq; ssaj q;3u9{ jo jbjbos b st ;T_nsai uoi;duiij aq; 

jl jy ja;siSaj ui y^d b sb paujn;9j si aiqBA aq; 'ja;uiod ajduns b si 

;nis9j uoi;ounj gq; ji -paujn;aa Suiaq aiqBA jo adA"; aq; uo Suipuadap 

'Ajoiuaui jo sj9asi3gj ui si aouajaiaj uotpunj b Aq paujnaaj aynsaj aqj, 

sau;ua ;stj ja^auiBJBd jbuuou 

aq; q;iM papnpui si papsoj 9q o; ;gA J9;auiBJBd aq; 'sja;auiBJBd jaq;o 

SuissBd asn ui Apsajp bjb sj9;si39j pgjmbgj 9q; ^b jj ;sq ja;auiBJBd 

IBti;db aq; jo ;jaj aq; uiojj 3ui;jb;s papBOj bjb saa;auiBJBd aq; puB 

'AjaAtpadsaj 6X P UB W H^T M Sui;jb;s panu 3-tb sja;si3aj aqj, ja;siSaj 

b ui ;ij ;Bq; sadA"; aissq jaq;o aq; ssbcI o; pgsn 9jb sjg;si3ai x 3t fl 

pus sjg;uiod ssBd o; pgsn 9jb sj9;si39j y aqj, qx qSnojq; 6X P UB 

gy qSnojq; yy sjg;siS9J ui pgssBd 9jb ja;si3aj x J0 V UB U T m l^m 

saa;auiBJBd aq; '(paoBpgp 9;nqu;;B qoox J0U J3HX 3I # J3q;pu aABq 

;Bq; asoq; 'si ;Bq;) saouajajaj uoi;ounj puB ajnpaoojd [Buja;ui joj 

S33uajaj9j gjtipaDGjd 

joj asoq; sb 9uibs aq; ajB saouajajaj uoi;ounj joj suoi;u8auoo 

ja;siSaj aq; 'ajojajaqj, anjBA b sujn;aj ;sq; ajnpaoojd b sb jo 

;qSnoq; aq ubd uopDunj y gy o; uor;rppB ui sj9;slo9j 9saq; jo \\& asn 

sajnpaoojd [Buja;uj ^y puB 'gy 'xy sja;sifaj asn sajnpaoojd [Buja;xg 

ajtipaaojd aq; jo uoi;naaxa ffriunp sanjBA jaq;o 

pau3issB aq Abui jjx qBnojq; 6X P UB '&V q3*iojq; yy 'gy sj9;si39ii 

'AsnoiA9jd uMoqs saniBA gq; umuoo sXbmtb zy rub 'tv 'ny saa;siSaw 



How Parameters are Passed 



How Parameters are Passed 

The following paragraphs describe how parameters are passed for 
reference parameters and value parameters, and calls between 
languages. 

Reference Parameters 

■*- v* -*■ ^j.\-i vnvv ^/cu GiAiSvCi Sj ti puiiiuci ui/ uj.±o a\<iuai via. lci is gcuci aucu 

and the pointer is passed as the parameter. The parameter is 
left-aligned on a word boundary. 

Value Parameters 

If the parameter length is less than or equal to a word, a copy of the 
actual parameter is made in the parameter list. The parameter is 
right-aligned, but on a word boundary. 

If the value parameter is larger than one word in length, the 
parameter list contains a pointer to the actual parameter or a copy of 
the actual parameter (this pointer is left-aligned on a word boundary). 
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Si-j itramuojiAng anni-uny qiaAO 3«IL d uotsiabh 



■jtbo ajnpaooad aq; uo paauajajajap 
si j3;uiod sq; puB ja;uiod b si a^qBUBA oi;Bino;nB aqj, - 

t9{qBTXBA Di;BUI0;nB 

aq; pauiiap ;Bq; aonpamid aq; jo adoos aq; urq;iA\ ajnpaaojd 
pa;sau b ui paiirpoin si ajqBUBA oi;buio;iib aq; puB '3tc[btjba 
3i;Buio;nB aq; pauiiap ;Bq; ajnpaaojd aq; jo adoas 3q; uiq;iA\ 
ajnpaoojd pa;sau b o; pagsBd Buiaq si a^qBiiBA 3i;BUio;nB aqj, - 

!;u3ina;B;s 

tjbd aanpaaoad aq; ui 3jc[bijba oi;BUio;nB aq; jo ssajppB aq; ssBd 

o; pasn si uoi;ounj 001# JO roquets v aq; jo 'uoi;ounj Q01# 

aq; jo ( v ) ToquiA"s aa;uiod aq; Suisn ;u3raa;B;s ;uauiu3issB 

ub ui ajqBUBA di;buio;tib aq; o; pa^BaauaS si .ia;uiod y - 

lajnpasoad Bmuijap aq; jo adoos aq; uiq;iA\ itbo 
ajnpaDojd aub ui aouaaajaa Aq passBd si ajqBUBA Di;Biuo;nB aqj, - 

:suoi;ipuoo Suimotjoj aq; jo auo japun 
idaDxa 'aa;auiBjBd biitba b sb passBd si ;Bq; a^qBUBA oi;biuo;tib 
(pj0A\ auo uBq; jagjB^ 'si ;Bq;) sSjbt^ b jo apBui ;ou si XdoD y * 

ajnpaoojd naTiTja 
aq; ui paidoo aq [jiav ;Bq; aa;auiB.iBd b jo apsui ;ou si A"doo y » 

ja^auiBJBd 
anp3A b sb passBd si ;Bq; ;ub;suod aSjBj b jo apBiu ;ou si A*doo y • 

paijpads a;nqij;;B aV3H 9 VH <DP^ uoi;oas Ajouiaui 
b jo ;jBd sb pauiiap si ;Bq; 3{qBijBA b jo apBiu ;ou si Moo y « 

ajnpaaojd aaq^ouB o; ja;auiBJBd 
an[BA b sb passBd si ;Bq; j3;ainBJBd anp3A b jo apsui ;ou si A*doD y * 

:(aanpaooad Sutijbo aq; ui saa;araBJBd siitba aSjrei SuiacIod joj sapa 

aq; bob asaq;) suoi;ipuoD SuiMonqi aq; japun ;stt. ja;auiBJBd aq; ui ;nd 

si b;bp aq; o; ja;uiod b 'pBa;sui 'puB 3[db;s s ( j3t_jbd 3q; o; paidoo ;ou si 

jaisuiBJBd aniBA aui 'jsasmou bibd aui io 8dbui si A"doo b 'a"ttbuliont 



passBj ajB sja^auiBjBj iaojj 



How Parameters are Passed 

Value parameters in the prolog of the called procedure are copied if 
the called or nested procedure generates a pointer to the value 
parameter via the pointer symbol (*) or the #LOC function and one of 
the following conditions is true: 

• The pointer is passed as a parameter 

• The pointer is not an automatic variable of the procedure 



• 



• 



A pointer to the pointer is generated in an assignment statement 
using the " symbol or the #LOC function 

A pointer to the pointer is passed in a procedure call using the A 
symbol or the #LOC function 

The pointer is dereferenced on the left side of an assignment 
statement 

The pointer is dereferenced on a procedure call and the call is by 
reference 

• The value parameter is a sequence or structure that contains a 
sequence, the pointer is generated to the sequence, a data item 
pointer is generated into the sequence with a NEXT statement, 
and the data item pointer escapes (that is, one of the items 
previously listed occurs) 

If the called procedure or a contained procedure generates a pointer to 
the value parameter and the value of that pointer escapes or the 
object of the pointer is altered, the called procedure's prolog copies the 
parameter to its stack frame. The prolog also generates a pointer to 
the copied data and stores it in the called procedure's stack. 
Generation of the pointer to the parameter is performed because the 
caning proceuure may ue executing in a diuerent ring than the called 
procedure. 

Calls Between Languages 

If a call could be made to another language and it has a system 
format actual parameter list to be passed that contains only reference 
parameters, the parameter list is immediately preceded by a word 
whose value is the 64-bit integer zero. This word need not precede 
any other system format actual parameter lists, only those for calls to 
another language. 
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il-tf inamuojiAaa auni-una 1IHAD a m d uotSTAa^ 



pjooaj aq; jo spray jo a"bjjb aq; jo s;uamaTa Smpuodsajjoo 

aq; jo sadA"; aq; qo;BTu ;snui passaooB b;bp aq; jo sadA"; aq; ';uauoduioo 

Aq ;uauodmo3 paAau;aj si aouanbas b ut paoBjd pjooaj jo a"bjjb ub ji 

pjoooj aq; jo spjaTj jo abjjb aq; jo s;uauiaia q;joj 
os pus 'pjnj; 'puooas aq; o% sjajuxod piaTA" pjnoM sadA"; ;uauoduioa 
aiBTjdojddB jo sja;mod uo pauuojjad s;uauia;B;s j,X3N ^anbasqng * 

pjooaj aq; jo pjaTj jo abjjb 
aq; jo ;uauiaja ;sjtj aq; o; ja;mod b piaTA" pjnoM adA"; ;uauodui03 
a^BijdojddB aq; o; ja;uiod b uo parajojjad ;uauia;B;s iX3N V • 

:aru; aq praoM s;uauia;B;s Sutmojioj aq; 'pjooaj 

jo Abjjb aq; o; ;asaj sbav aauanbas aq; ptre aauanbas b ut paaB^d 

sba\ pjooaj jo Abjjb ub ji 'st ;sq; ijapjo jbjti;bu Jjaq; ut Ajouiaui 

o; paddBui 3jb spjoaaj puB sAbjjb paspBdun jo s;uauoduioo aqj, 

paAjasaj st aoBds ou 'paouajajaj 

;ou st a^qBUBA b ji auop st SuTjapjoaj ou ;uiBaj;s ;ndui aq; 

ut jtiodo Aaq; ipTqM ut japjo aq; ut pa;BDOjTB st sajqBTJBA joj aredg 

uopeooflv ^I'H^A 

Mourf noA s;aj pus sipaqo japsoj 

aq; 'saun; asaq; uaaA\;aq aSuBqo saoBjja;uT aq; puB saun; ;uajajjrp 

;b sapnpoui ayrduioo noA jt ;sq; suBara snij, '(191 qq st apoo uot;tpuod 

aq; puB HOJ J VWSM~NOIiVHV10a<I$a r rc S T -rayP u3 P! uopjpuoo 

aq;) sjojjb uoT;BOTjrjaA ja;auiBJBd aq; Suriuaumoop aSBssaui jooja ub 

saraiauaS jsoboi am 'aajllB iou od Aaua it aajSB sstobuba oaouaiaiaj 

pus pajBpap AjTBUja;xa [jb joj sadA; s;sp aq; ;Bq; ajnsua o; sarqBA 

qsBq asaq; s^Daqo japBO{ aq; 'uorinoaxa ajojag ssaaojd aq; ui papnpui 

st (j8;91ubjbu [Buxjoj qc>B8 jc= <s&&% aq; jo aniBu aq;) ;sij aa;auiBJBd 

aq; 'sajnpaoojd jo^'SurdA; b;bp aq; jo uopBpumoDB ub uo pasBq 

st qsBq STqx paouajajaj jo pajBpap AjjBuja;xa st ;sq; ajnpaoojd pus 

a^qBUBA qoBa joj pa;ndui03 st qsBq b 'ssaoojd uopBnduioo aq; Sutjuq 



saonojioja>[ xbuisxz^. 



X"H suotjBpuarauioDay Sutmin-BoSojij j uoista^jj 



:g =: [xapui]* 

■ \ =■■ xapui. 

:g =: A 

:j36a;ui }0 [36ubj~b] Aejje = x 
'36ubj~b :A 'xaput 

bVA 

; 0l" " = 36UBJ~B 

3dAl 

•siq; sa;Bj;sn{Ti ajduiBxa Suiaio[toj aqj, jTas;i 

adA; aji;ua aq; ireq; jaq;Bj sadA; jo saSiiBjqns Sutsn 'os op o; 

pa;Bjaua3 aq ;smn ;Bq; apoo jo ;unouiB aq; aziuiTuroi o; oibjSojcI 

jnoA" apoo ;nq Suppaqo aSuBJ ;sanbaj o; 'ajojajaq; 'ajqBjajajd si ;j 

pasouBBip aq ;ou abiu sjojja uiBjgojd a;Bun;i3at 

asriBoaq papuoumioaaj ;ou si uiBoSoad jnoA" SuiSSnqap bjb 

noA aiiqAv gNON °* SX03HD - 3K[LLNnH SuTW»s 'jaAaMOH -JIos;i 

uiBjSojd aojnos aq; in & (&$q = : ON3MHO)iaS 6i aAipaJip aq; 

apnpux jo 'puBuiuioD hhaO aqi u0 aNON=S3I03HO~aWLLNnH 

Ajpads 'Suppaqo aSuBJ jjo ujn; oj, ajqissod sb qonui sb Suppaqo 

aSuBj ptoab o% aiBjSojd aojnos jnoA apoo jo (Surtnnsuoo-aun; 

si pus 33bjo;s [BuoptppB sajmbaj ;t) Suppaqo aSirej tjb jjo xunj, • 

•Aouapijia apoo aajnos SutAOjdmi joj suot;saSSns ajB Sutmoijoi aqj, 

iCouaioijja apoQ aoanog Shisbdjeoui 

aoBjajd aq; ut s;uaxuraoQ 3ui;;nuqng 

japun uMoqs ssajppB aq; o; oiaq; puas jo psmraui aq; jo ipeq 

aq; in ;aaqs ;uaurai03 aq; Suisn sn o; raaq; puas asBaid 'aouBuuojjad 

aAOJdrai ;Bq; punoj aABq noA spoq;aut jaq;o ajBqs o; ajjij ppnoM noA jj 

apoo jnoA jo A;uBp aq; ;oajiB ;ou op 

Aaq; tiaqav Apio pasn aq ppoqs Aaq; 'suornjpuauiuiooaj §urainiBj3ojd 

Aub q;iAv sy aim; SinpBoj puB uoT;BTiduioo aAOjduit pus apoo 

aajnos jnoA jo ADuapijja aq; asBajDiri ubo noA sAbav s;sq xipuaddB siqj, 

II suonBpuauiinooaw SuiuiuusjlSojla 



Increasing Source Code Efficiency 

This example declares a subrange from through 10 to be a type 
named A_ RANGE. The variables INDEX and Y are of type A_ 
RANGE, the subrange. Therefore, the assignment statement 

index := y; 

is not checked for range violations even if range checking has been 
requested. Likewise, the assignment statement 

x[index] := 3; 

is not checked. If, however, the variables INDEX and Y had been 
declared integer or some other type besides a subrange, range 
checking code would have been required. 



• 



• 



• 



Turn off all checking options when you compile the code to 
improve execution time. 

If you call a procedure repeatedly within a loop structure, call the 
procedure once and put the loop tests inside the procedure to avoid 
significant overhead. 

Observe that a procedure should reference only static variables, 
arguments, and its own automatic variables to avoid overhead 
associated with those references via the static link. 

If a comparison of two records occurs, organize the fields within 
the records so that the fields most likely to differ appear first. 

Move a single structure of elements instead of many individual 
elements. This may require arranging the elements specifically for 
this purpose (for example, within a record). 

Reference a fixed-size structure rather than an adaptable structure, 
because the adaptable structure has a descriptor field that must be 



Reference fields within a record, as it causes no extra execution 
time. 

If you are repeatedly referencing a complex data structure (by 
pointers or an indexing process), use a local pointer to access the 
structure and replace the more complex references. 
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g-H suo^Bpuatauiooay SumcatBiSoi^ ^ noisiAay 



ua^SBj qomn 'ajoj3jaq; 
'st puB apoo aurTUT sb pa:iuaui3TduiT st ;i sb '(s^uaaia^Bis 33^3 puB 
3iLV0O r nv a H* Suiurquioo UBq; jaq^Bj) luauia^s HSfld 9t H 9S fl • 
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Increasing Source Code Efficiency 

• When specifying a pointer, use the pointer symbol A rather than 
the #LOC function, to promote efficiency and maintainability. 

• If the definition of a structure contains many flags or attributes, 
consider the following when choosing between a boolean type and a 
set type: 

- If the record is unpacked, using the set type reduces the size of 
the definition. 

- Any subset of the attributes of a set can be tested immediately. 

- If you are testing a single element, an unpacked boolean type 
is more efficient than a set type. 

• Use boolean expressions rather than conditional statements, as 
they are more efficient. For example, the statement 

equality := (a = b); 

is more efficient than the IF statement 

IF a = b THEN 

equality := TRUE; 
ELSE 

equality := FALSE; 
IFEND; 

• When possible, use a CASE statement rather than a long, complex 
IF sequence. This can be done when the value of a single variable 
determines the sequence of action. 

• Arrange compound boolean expressions so that the first condition 
evaluated is the one most likely to end evaluation of the entire 
expression. 
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Increasing Source Code Efficiency 

• Use the ANALYZE_PROGRAM_DYNAMICS command and the 
Measure Program Execution Utility to study your program's 
efficiency with respect to execution time, page faults, and module 
connectivity. Both are described in the SCL Object Code 
Management manual.For more detailed data collection and 
reporting, use the ACTIVATE _JOB_ STATISTICS command or, if 
you have the required permission, the ACTIVATE_SYSTEM_ 
STATISTICS command, and the Display Binary Log Utility (refer 
to the System Performance and Maintenance manual). 

• Bind programs to improve overall load and execution time. You 
can bind programs with the ANALYZE. PROGRAM. DYNAMICS 
command, the Measure Program Execution Utility, or either of the 
Object Library Generator subcommands CREATE. MODULE or 
BIND_MODULE. All of these commands and utilities are 
described in the SCL Object Code Management manual. 

• Create a linked module for large programs with a great deal of 
static data. For further information on linked modules, refer to the 
SCL Object Code Management manual. 

• Organize the frequently used variables first in large user stacks to 
avoid reaching the threshold of the load and store instructions 
(2 16 ), causing an extra instruction to be generated to handle the 
offset. 

• Check the default values for compilation options and use the 
appropriate values. To improve performance, select optimization, if 
possible. Unless you are debugging code, avoid selecting stylized 
code for debugging and range checking; both generate extra code 
and cause greater execution time. 
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Use of equality (=) and inequality (<>) relationships on records. 

Subranges and the ELSE option as CASE statement selections. 

The CELL and pointer to cell types, and the #LOC and #SIZE 
functions. 

Data mapping as described in appendix E, Data Representation in 
Memory. 

The evaluation of condition terms proceeding from left to right and 
ending when the value of the condition is determined. 

Pointer to procedure and pointer to function type. 

The relative pointer type. 

Special characters _, @, #, and $ permitted in names. 

Comments terminated by an end of line. 

Multiple instances of CONST, TYPE, VAR, and procedure 
declarations permitted in any order. 

The reserved word RETURN as a control statement. 

EXIT and CYCLE followed by a group label as control statements. 

CASE statement selectors delimited on both sides by the equal 
sign character (=) rather than only on the end by the colon 
character (as in Pascal). 

Control over data locality using the SECTION declaration. 

ivestricteu auiiity to generate certain mime instructions using 
intrinsics. 

The ELSEIF option associated with the IF statement. 

Compilation time facilities. 

Hexadecimal, octal, and binary numeric constants. 

Detection of side effects from programmer-defined functions. 

The bound variant record type. 
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The implementation of the following items differs: 

• The CASE statement syntax. 

• Designation of the end of declarations and statements (use of a 
semicolon rather than an end of line). 

• Designation of comments. 

• Externally referenced variables, functions, and procedures (use of 
the XREF attribute rather than EXTERNAL). 

• Names of certain functions ($CHAR instead of CHR, $INTEGER 
instead of ORD, and STRLENGTH instead of MAXLENGTH). 

• Reserved (predeclared) names as listed in appendix D, Reserved 
Words. 
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Types 



cyc$unknown_contents = 'UNKNOWN 

cyc$detach_file = cyc$return_f i le; 

cyc$max_fi le_name_size = 512: 

cyc$min_ecc = (($INTEGER('C')*100(16))+$INTEGER('Y')) 

•1000000(16); 
cyc$max_ecc = cyc$min_ecc + 9999; 

cyc$min_ecc_cybil_input_output = cyc$min_ecc + 6200; 
cyc$max_ecc_cybi l_1nput .output = 
cyc$min_ecc_cybi l_input_output + 99; 

cyc$page_ limit = 439804651103; 

cyc$title_size = 45; 

cyc$wide_page_width = 132; 
eyc$narrow_page_width = SO; 
cyc$max_page_width = 65535; 



Types 



cyt$close_f He_disposition = (cyc$delete_fi le, cyc$retain_file, 
cyc$return_f i le, cyc$unload_f i le, 
cyc$default_f ile.disposition); 

cyt $cur rent _file_posit ion = (cyc$beginning_of_information, 
cyc$middle_of .record, cyc$end_of .record, cyc$end_of .block, 
cyc$end_of .par t i t i on , cyc$end_of _ i nf ormat i on ) ; 

cyt$fi1e = "SEQ ( * ); 

cyt$f i le.access = (cyc$read, cyc$write, cyc$read_write); 

cyt$f i le.character.set = (cyc$ascii, cyc$ascii612, cyc$ascii812, 
cyc$display_64, cyc$reserved_code1, cyc$reserved_code2) ; 

cyt$file_contents = string (31); 

cyt$f i le.existence = (cyc$new_f i le, cyc$old_f i le, 
cyc$new_or_old_f i le) ; 

cyt$f ile_kind = (cyc$binary_f ile, cyc$display_f i le, 
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= SS333B~31U$3A3 = 
'PUL>|-31LJ$JA3 :pui>|~3ltJ 

= puiJj~aiLi$DAo = 

JO J0^3aiaS - U0L^E3U103dS~3l LJ$;A3 :J04.33L3S 3SB3 

PJ033J = uoiiB3ULoads~ai ljs^As 

: (LS) 6UIJJS = J0SS330Jd~3l LJ$JA3 
:(3ZlS~aUIBU~3t IJ~XBUJ$3A3 => * ) 6ULJ1.S = auiBu~ai LJ$)A3 
'. (31 U~1X31$3A3 '31 U~DJ033J$3A3 



Types 



cyt$f i le_specifi cat ions = "array [1 .. * ] of 
cyt$f i le_specif ication; 

cyt$file_specification_selector = (cyc$f i le.kind, 

cyc$f i 1 e_access , cyc$f i 1 e_ex i st enee , cyc$open_pos i 1 1 on , 
cyc$c 1 ose_f i 1 e_d i spos i t i on , cyc$f i 1 e_cont ent s , 
cyc$f i 1 e_processor , cyc$f i 1 e_charact er_set , 
cyc$new_page_procedure , cyc$page_ length, cyc$page_width, 
cyc$page_ format ) , 

cyt$new_page_procedure = record 

case kind: cyt$page_procedure_kind of 
= cyc$user_specified_procedure = 

user_procedure: cyt$user_page_procedure, 
= cyc$standard_procedure = 

title: string (cyc$title_size), 
= cyc$omit_page_procedure = 

casend, 
recend ; 

cyt$open_close_position = (cyc$beg inning, cyc$end, cyc$asis, 
cyc$def au 1 1 _open_pos i t i on ) ; 

cyt$page_format = (cyc$continuous_form, cyc$bur stable. form, 
cyc$non_burstable_form, cyc$untitled_form) ; 

cyt$page_ length = 1 .. cyc$page_ limit ; 

cyt$page_width = 1 .. cyc$max_page_width; 

cyt$page_procedure_kind = (cyc$user_specified_procedure, 
cyc$standard_procedure, cyc$omit_page_procedure) ; 

cyt$skip_di recti on = (cyc$forward, cyc$backward) ; 

cyt$skip_unit = (cyc$record, cyc$block, cyc$partition) ; 

cyt$system_type = (cyc$nosve, cyc$nos, cyc$nosbe, cyc$vsos, 
cyc$eos, cyc$aegis); 

cyt$user_page_procedure = "procedure (display_fi!e: cyt$file; 
next_page_number .- i nteger ; 
VAR status: ost$status); 
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S-P 0/1 1IHAO J0 J saoRBJBpaQ adXj, puB iubisuoq ^ noisrAa^ 



'■ pueas j 

'PU3SE3 

= anai = 

'3pO3~UOlHPUO0~SmB}S$lSO :UOlUPUOO 

= 3S"IVd = 
±a ueaiooq : ieidjou sseo 

njooaj = sn is is* iso 



S8<KL 



I-H O/I IISAO JOJ sa3BSS8H 



j U0ISIA9JJ 



Cpajioour st „avaH$OAO 

'3na~M3N$DA0„ 'aidiuBxa 

joj) aanpaaoid uddo ire o; usaiB sbav 

sia:iauiBjBd jo uopeutquioa pqBAm uy 

a.mpa30jd ana~aV,l$dAO 9l tt °? 
passBd sbav x uetji ssaj uumjoo-qB; y 

a.mpaoojd aoyd 

"AvidSia'NOiiisod^dAO »q» o* 

psssBd sbav x usq; ssaj aaqumu auq y 



;n<Hno ioj A*pao pauado sbav ;Bq:i ajri 
b uioaj pB9J o; apsra sbav ;duia#B uy 

■iua;sA*s Sut^Bjado 

8UJ JO SUOTJU3AUOD SuTUIBU 3\Q 31$ 
0^ UIJOIUOD }0U S90p IBTfl 3UIBU B qjIAV 

arrj b aado ai apBui sbav ^draa^B uy 

ua\0U3[ ;ou st auiBu 3jrj aqj, 
sajnpaaojd uado aq; jo auo usq; jaq;o 
aanpaaoad o/I 1I3A0 B °1 p^ssBd sbav 
ajTjJ^Xo adA"; jo a^qBUBA pauTjapun uy 

A\0jp3 TJTAV 

iua;sAS SupBjado aq; UBq; sia;3Bxeqa 
aioui SBq auiBu ajrj paTjpads aqj. 



auiBua^ij 

ana aoa xsanoaa 
N3d0 loaaaooNi 

araBuaiTj alia H03 

Nwmoo avj, ioaaaooNi 

auiBuajii 

ana aoa NOiusod 
3Nn Avidsia xoaanooNi 

auiBuajri 

ana noa xsanbaa 
xndNi xoaaaooNi 



9UIBUaTTI 

'arcvN ana xosaaooNi 



N3do xon ana 



aureuajrj 
'ONOT 001 3IWN 3113 



SuTUBaj\[ 



aSBSsapvj 



a;BTduia; 
aSBSsaui aq; ui sjBadde aSBSsaui aq; uaqM ajri DTjpads b jo auiBu aq; 
A*q paoBida.1 aq [ttm auiBua^ij 'Avojaq pa;sTj suoijdiJDsap aSBssara aq; ui 

O/I 1I3A0 as fl °i M0 H '6 Ja;dBqa ut paquasap si ajqBUBA stq; Aq 

paujn^aa pjooaj sti;b;s aq; jo ajn;otu;s aqj, ja;auiBJBd aiqBTJBA sti;b;s 

aq; in paujitiaa aq ijtav uotxjpuoo sii;b;s aq; 'sasiJB suot;tpuoo ssaq; 

jo auo ji jojja ub jo uoT;oa;ap uiojj jo o/I 1I9A0 J° 9Stl -Jadoadun aq; 

jaq;p iuojj ;jnsaj abui ;Bq; saSBSsara su;b;s aq; saquosap uorpas stqj, 



M 



n/T nffii joi saSBSsarAT 



j.j.«j.j.x.a«^ 



INVALID OPERATION 
ATTEMPTED ON FILE 
filename 



INCORRECT OUTPUT 
REQUEST FOR FILE 
filename 

INCORRECT SKIP COUNT 
filename 

KEY BEYOND E-O-I ON 
FILE filename 



PREMATURE END OF 
OPERATION ON FILE 
filename 



NO MEMORY TO OPEN 
FILE filename 



An operation was attempted that does 
not match the FILE_KIND specified 
for the file on the call to the open file 
procedure. (For example, a 
CYP$GET_NEXT_BINARY may have 
been attempted on a file opened as a 
text file.) 

An attempt was made to write to a 
file that was opened only for input. 

A skip count less than -1 was passed 
to the CYP$SKIP_ LINES procedure. 

An attempt was made to perform a 
binary file operation with a key that 
was outside the bounds of the file (in 
other words, the key did not specify a 
random address that is in the file). 

A boundary condition was encountered 
during the CYP$POSITION_ 
RECORD_FILE procedure before the 
count was exhausted. 

There was insufficient space to 
allocate the descriptor and/or buffer 
for the file. 



COULD NOT FIND FILE An attempt was made to open an old 



FILE filename ALREADY 
EXISTS 



.en _ j.t j. rfT^rriTT t i/-\ _ -_ 

nie uia.L v/iduj u\j cainiOL imu. 



An attempt was made to open a new 
file but a file with that name already 
exists. 
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X-xapuj nopjraipQ aSwiSuBq UHAO 



£ HOISTAa^ 



i 8i-6 ^aiq 

aoNvOMiNOis~ou.awH.irav 

| 8Z--6 ~«" 

i A\.oiaHaAO~oiJiawHi 1 raVi 
si-a (div) ! 

ja^uiod }stj ^uaranSay 

T-V ISNV 

g-g jo^Bjado dNV 

X-y -iapB-reqa DTjaumuBqdjy 

T-y i&\DVXBip apaqBqdjy 

js^utod 

^sij ^uaranSoy aas 'jqy 

il'l-a MBds jo uoi^BDonvj 

Zf-q iBtruog 

88-g ajdurexg 

Zf-9 uoi^iinjaa 

^uama^B^s aiVOOllV 

XSWtS'OS-fr Ja^tuBiBd 

9I-g sajdurexg 

X-g Ajoraaui ui b^bq 

ISWfrS'OS-t -laiauiBJBd 

aaNonv 

Ol-L 
^SI-9 '8-8 -ST'ST-Z <«ubu SBT[y 
SX-8 aA"oanp aSBd aouBApy 
8-y o-oquuCs 

S-V appow j 
g-y auiqoBj\[ 

OX-6 SnqaQ j 
Sl"6 sapipoui punog 

Suissaippy 

gg-e uorpnnj ssaaaav# 

g-g sao^Baado uopippy 

g-g uopBaado uopippy 

9X-t o% sja^upd 

8g-g ajdurexg 

g-*- }uap3Ainbg 

8^-t uoiiraijaa 
sacLfy ajqB}dBpy 

ig-e asiG 

Qf-f }Buuog 

9-g JCKjduosaa 

Qf-% uoi;xuuaQ 

Suij^s a^qB^dBpy 

' iS-S 3~S 
gg-^ iBuuog 



8g-g aiduiBxg 

£-g jo^duosaQ 

8S"t uopraxjaa 

aauanbas ajqB^dBpy 

OX -a i~;inod aAi^Bjaj ajqB^dBpy 

A8-9 3ZTS 

Xg-f- v*miO£ 

2,-g jo^duosa(j 

Xg-t uopiurjaQ 

pjooej 9[qBidBpy 

9-3 'iS-9 aziS 

ox-a 3At?Biaa ! 

9-g ;uauiu3nv i 
aa-juiod axqB}dBpy| 

L2-9 s~S ! 

gg-t }Buuog | 

2,-g jo^duosaQ 

8S-t aoT^TUTjaQ 

dBaq ajqB^dBpy 

9'g-g jo^dijosap ajqB^dBpy 

LS-S 3~S 

Qf-f ;Buuog | 

88-g atduiBxg ; 

9-g aatduosaQ j 

6t-t uoi^iuijaa ' 

abjjb a^qBjdBpy 

SX'SX-L ajnpaoojj 

02 £ 8I"9 uoppung 

saa^auiBJBd pmpy; 

X-V ! 

■83"i/ ja UFl ua PT ^uauiSas aApoy 

X-y ureqo ijbo aAtpy 

g-g s[btiubui ampio Suissaooy 

g-g sjibj uiBoSojd b uaq\^ 

g-6 uopnoaxa 

VUBjSoJLd §UIJtlQ 

gg-6 io.ua 
arap-uorjnaaxa ub aayy 

SnqaQ Suissaooy 

X"V -9-8 «Hnqi~4B ssaaoy 

g-g ainqmiB aiM^XHOSV 

g9-6 ^Bidsia 

68-6 aSireqo 

saaasiBaj v 



^uajq aONVOMINOIS OIXaMHXMV 



xapuj 

sja^stSsj v 



Array 



Byte offset 



Array 

Adaptable 4-49 

Alignment E-2,11 

Definition 4-25 

Elements 4-27 

Examples 4-27,28 

Format 4-25 

Initializing elements 4-26 

LOWERBOUND function 6-4 

Referencing elements 4-27 

Size 4-25; E-2,11 

Subscript bounds 4-25 

Two-dimensional 4-28 

UPPERBOUND function 6-13 
ASCII A-l 

ASCII character set C-l 
ASID, see Active segment 

identifier 
Assigning 

Elements of a set 4-42 

Pointers 4-13 

Registers F-12 

Strings 4-24 
Assignment operator 5-17 
Assignment, set 4-42 
Assignment statement 

Compile-time 8-9 

Definition 5-15; A-2 

Format 5-15 
Attribute(s) 

Access 3-6 

Debug 9-3,5 

Effect on initialization 
by 3-16 

Function 6-15 

#GATE 3-4; 6-16; 7-11 

List 8-3 

Procedure 7-10 

READ 3-3,6 

Scope 3-8 

Section name 3-4,11 

STATIC 2-12; 3-4,10 

Storage 3-9 

XDCL 2-12; 3-3,8 

XREF 3-3,8 



itoxuatic variable 



F-3 



Oil. O Q. 

*-j-x, o-b, 



B 



Basic types 4-4 
Batch Debug 

Definition A-2 

Example 9-104 
BDP A-2 
BEGIN statement 

Definition 5-19 

Format 5-19 
Binary object code, listing 8-3 
Bind map 9-15 
Binding programs G-6 
$BINDING section 3-12 
Binding section pointer 

(BSP) E-9; F-12 
Bit A-2 

Blanks in syntax 2-8 
Blocks 2-10 
Boolean 

Alignment E-2,3 

Constant 2-5 

Definition 4-7; A-2 

Difference 5-5 

Example 4-7 

Format 4-7 

Size E-2,3 
Bound module addressing 9-15 
BOUND parameter 4-33 
Bound variant record 

Definition 4-36 

Equivalent 4-3 

Pointer to E-8 

Relative pointer to E-10 

Tag field size 5-37 
BRANCH break 9-78 
Break report message 9-10 
Breaks, Debug 

Definition 9-9; A-2 

Delete 9-42 

Display 9-43 

Set 9-77 
BSP, see Binding section 

pointer 
Byte A-2 
Byte-aligned E-3 
Byte offset 2-6; 6-25,27; A-2 
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g-xapui noiinnjaa 83m3uBq iigAO 



^ uoisiAay 



I-g ibhijoj XSMOO 
g-y uopniTjea 

aaipuBij uoi^ipuoQ ( 

8-6 Pl^J NOIiidNOO 
8-6 3nqaQ 'apoo uoprpuoQ 

fZ-f -9"S uopBuejBOuoQ 

gg'0g-8 93Bds ssejduioQ 

gX-t adA; ^uauodraoQ 

f-$ ^9s 'nuauiaidraoQ 

gX-g uopBjado luauiaidraog 

X-8 apoa aajnos gutjiduiog 

g-V uoprayaa : 

XX-fr saSuBjqns jo SuppaijQ 

J9[tduiOQ 

g-8 sajqBUBA 

OX-8 luauiajBjs ai 

6-8 suoissaadxg 

i'X-Q ^ouaioi^a 

2X-8 seArpana 

6-8 luauia^s ^tiauraSissy 

3Uip-8[TdaiOQ 

^X-8 3Apo3Jip aildHOO 
X"8 ^ro" uoi;B[iduioQ 

g-V 9UIIJ, 

8-8 s^uauia^Big 
g-8 Supsn | 

8"8 SUOI^BJBp8Q 

3-8 IFO 
uoi^Biidutogj 
fZ-f sSuixfs SuUBdUIOQi 
ZZ-L a-mpaoaid ! 

dVMS~aavdK[oo# 

8-V ; 8-Z s^uaaiuioo 

tX-8 aApoanp iNaiOTOO 

n'SI-8 aAijoajip 

loa^uoo ^ueraraog 

Og-8 ipojq ^uamuioo 

9-6 »IB ONVIttlAIOO 

9-g ^U3T0TJJ9O0 
22"6 13IT30d '9D03 

3-8 'ZS'L uoT^BzroiT^do apoQ 

6-g ja^uiod assq apoQ 

32-£ uononjisux vXdWO 

g-H uotpunj HHO 

22-8 3\83o% anSSHO 

22-8 aiSSo* ONHHHD 

32-8 aiSSo* UNHHO 

22-8 atSSo; TIVSHO 



6S-6 



I-Z PTI^A 
S'2-3 8Z TS 

9-^ ^BUUOd 

9-^ ajduiBxa 

2-v -9-* uoi^iutjaa 

8-V ; S-Z Iub^suoo 

X-y 3iJ3nmuBqd[y 

X-y DrjaqBqdjy 

g'2-3 ;u9uiuSnv 

J3^0BJBq3 

puBuiuioDqns JTVHO 
2-9 uotpimj HVHOJ 
t£-6 puBtnmooqns AdVHO 
gg-6 puBtaraooqns 

Ha,LSioaH~aoNVHO 

f£-Q puBuiaiooqns 

amvA"Mvaooad~aoNVHO 

08"6 ptiBuiuiooqns 

AHOW3W~3DNVH0 

iZ"6 puBrauiooqns 

,nnvaaa~aoNVHO 

puBunnoaqris HVHO 

puBoiuiooqtis QVHO 

3X-t ad^x 

f'Z-3. 3ZJS 

8X-t «» Ja^urod 

2X-t adA jo IBUUOd 

ZVV uoptugaa 

t-a wo\ 

tZ-t -9-Z iVOi 

6z-s aNasvoi 

62-9 }Buuoa 

Og-g sajdurexg j 

62-g uopitnjaa 

luauia^s aSVO 

uorpru;sui Q3STIV0 

uoppru^sui lamivo 

9X~i ajnpaDOJd 

02-9 uorpung 

saSBiiSuBT uaaa^ag 

SiniiBO 
ajripaooid ai~H3 r nV0# 



08-6 
LZ-6 



OZ-L 
OZ-L 



91-3 



OZ-L 



QZ-L PI J31IBQ 

9fr-6 SnqaQ 'ureqo [pO 

82,-6 ^B9Jq 1TVO 

82- A SuiSand 'aqoBQ 



n 



IBuuoj J.SNOO 



SniSjnd 'aqDBQ 



Constant 



DEBUG_OUTPUT attribute 



Constant 

Boolean 2-5 

Character 2-5 

Declaration 3-1 

Definition 2-5 

Examples 3-2 

Expression 2-7 

Floating-point 2-5 

Format 3-1 

Integer 2-5 

Ordinal 2-5 

Pointer 2-6 

Real 2-5 

String 2-6 
Control statements 

CASE 5-29 

CYCLE 5-31 

EXIT 5-33 

IF 5-27 

Overview 5-26 

RETURN 5-34 
Conventions 6 
#CONVERT_POINTER_TO_ 

PROCEDURE procedure 7-25 
CPYSX instruction 6-30 
CPYXS instruction 7-37 
CSF, see Current stack frame 
$CURRENT_LINE 

function 9-90 
$CURRENT_MODULE 

function 9-90 
$CURRENT_PROCEDURE 

function 9-91 
$CURRENT_PVA function 9-91 
Current stack frame 

(CSF) F-3,12 
CYB$DEFAULT_HEAP 

section 3-12 
CYBIL and Pascal 

differences H-l 
CYBIL command 

BIN ARY_ OBJECT 

parameter 8-2 

BINARY parameter 8-2 

DEBUG_AIDS parameter 8-4 

parameter 8-4 
Example 8-7 
Format 8-2 
INPUT parameter 8-2 



LIST_OPTIONS 
parameter 8-3 
LIST parameter 8-2 
OPTIMIZATION_LEVEL 

parameter 7-32; 8-5; 9-16 
OPTIMIZATION 
parameter 8-5 
PAD parameter 8-5 
RUNTIME_CHECKS 

parameter 8-6 
STATUS parameter 8-7 
CYBIL-defined elements 2-1 
CYBIL formatter 8-26 
CYBIL reserved words D-l 
CYBIL syntax 2-8 
CYCLE statement 
Definition 5-31 
Example 5-32 
Format 5-31 



D 



Data 

Alignment in memory E-l 

Examples in memory E-16 

Packed E-l 

Representation in 
memory E-l 

Size requirements E-l 

Types 4-1 

Unpacked E-l 
uo.\m. conversion lunctions 6-1 
Debug compiler options 8-4,5 
Debug functions 

$CURRENT_LINE 9-90 

$CUkkjsNt_MU1>ULE 9-90 

$CURRENT_ 
PROCEDURE 9-91 

$CURRENT_PVA 9-91 

Overview 9-90 

$PROGRAM_ VALUE 9-92 
DEBUG_ INPUT attribute 9-3 
DEBUG_MODE attribute 9-3 
DEBUG_OUTPUT 
attribute 9-3,5 
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g-xapuj uot^iuyag 33m3uBq qiaAO 



j uoisiAay 



g-y aa^iniipQ 
gt-6 ssjBaaq 3nq9<i 9}9i9(i 
2^-6 ptreuraiooqns 

W3Ha~aj,aaaa 

gfr-g pireaiaiooqns gqga 
02-6 s^Bgaq pauajaa 
LZ-6 Snqaa 's^nBjgQ 
2X-g dBaq nnnpa 
g-g aiqBUBA 
8I-S 3<*4l 
02-8 uorpag | 
SX-Z uiBiSaij ! 
OX-i aanpaDOJtd I 
X-x AvatAjaAQ 
8I-Z sinpo]A[ 
9X-9 uotpuiijj 
X-g ^ub^suoo 
g-8 uopB^Tdaiog 

SUOI^BJBX38Q 

^x-a j °** 9 

qD^BUisira uoi^BJBpea 
g-2 uohb^ou jBinpgQ 

§nq3Q 99s 'smBjSojd SurSSnqgQ 
S6-6 asn 
98-6 ap°«* <l9^s 
8-6 aiqBiiBA sn^g 



SZTO 



UOI3383 B joUI^ielg 



61-6 Suta 

Si"6 uoissas b Suruinsay 

OX-6 sesssjppB uiboSojj 

X-6 AvatAjaAQ 

82*2,-6 a HJ ^nd^no 

9X-6 3poa paznmjdo 

2,x-6 3ui3Snq9p ^SB^ppim 

I2 _ 6 ^uauiuojiAua Suuppnpj 

Xg-6 s^B9jq 9idp[tij\[ 

iX-6 §tnss9DOjd ^dnja^uj 

82'9"6 3 IU »nd«I 

A*J?U3 

aaBJBdas 99s 'suopptm^ 
9at;dbj9^ui jo ajduiBxg 

fQT-Q U0TSS9S 

qo^Bq jo ajduiBxg 

6^-6 ^uerauoaiAug 

fl-Q uoissgs b Suipug 

02-6 sip39jq pgajgjaa 

2,2-6 s^riBjaa 

;.t-b sj9tt>ubu uonrouo^ 



g-6 9poo uopipuoQ 

9^BJBd9S 99S 'SpUBUHUOQ 

Sfr-6 upqo HBQ 
LL'Zt'Zf 6-6 sifB9Ja 

0X"6 33BSS9UI )J0d9J ^B9jg 

SI _ 6 sapipoui punog 

g'g-6 sg^nqu^v 

22-6 J0JJ9 

9nip-uopnD9X9 ub aayy 

0X-6 Suissaappv 

g-6 3uxss90oy 

Affllift 3nq9Q 

g2-6 AjBuramg 

LL-6 WSiLaS 

ll-6 aias 
Li-6 aaowaais^as 

LL-6 XV3Ha~I,3S 

sa-6 Nna 
ti-6 unb 

89-6 assia 

39-6 HSId 
iS-6 AdSId 

89-6 ai\[vaa 
~HOvi,s~AvqdSia 
S9-6 Haxsioaa~AVTdsia 

Z-S-6 dil'l'VA 

~wvaooHd~AVidSia 
2S-6 AaowaH~AvidSia 

6^-6 iNaWNOHIANa 

"ONioonaaa "Avidsia 

S^-6 llVO~AVldSia 

sf-6 Hvaaa~Avidsia 

2S-6 WLSia 

6^-6 aasia 

9f8 osia 

s^-6 asio 

2^-6 svaaa'aiaiaa 

2f-6 aaaa 

68-6 HVHD 
f2-6 AdVHO 

68-6 aaisroaa~aoNVHO 
~wvaooad~aoNVHO 

08-6 AHOWaH~aONVHO 

L2-6 xanvaaa~aoNVHO 

08-6 WVHO 
i-2-6 aVHO 
spUBtatnODqns gnqarr 



aajTwnsa 



spuBmmoDqns SnqaQ 



Dereference, pointer 



Equivalent types 



Dereference, pointer 4-13 
Descriptor for adaptable 

object E-5,6 
Diagnostics, listing 8-4 
Digit A-3 
Direct pointer 

Converting from a relative 
pointer 4-19 
Directives 

Compile-time 8-12 

Formatting 8-32 

Text-embedded 8-1 
Directives, compile-time 

COMMENT 8-14 

Comment control 8-12,14 

COMPILE 8-14 

Definition 8-12 

EJECT 8-15 

General format 8-13 

Layout control 8-12 

LEFT 8-15 

LIBRARY 8-16 

Library control 8-12,16 

Maintenance control 8-12 

NEWTITLE 8-17 

NOCOMPILE 8-18 

Object library control 8-12,16 

OLDTITLE 8-18 

POP 8-19 

PUSH 8-20 

RESET 8-22 

RIGHT 8-23 • 

SET_ 8-24 

SKIr* 8-24 

SPACING 8-25 

TITLE 8-25 

Toggle control 8-12 
Directives, formatting 

Definition 8-32 

FMT 8-33 

General format 8-32 

LEFT 8-36 

RIGHT 8-37 
DISB subcommand 9-43 
DISC subcommand 9-45 
l/ioDE subcommanu 9-t9 
DISM subcommand 9-52 
Display area F-9 
DISPLAY_BREAK 
subcommand 9-43 



DISPLAY. CALL 

subcommand 9-45 
Display Debug breaks 9-43 
DISPLAY. DEBUGGING. 

ENVIRONMENT 

subcommand 9-49 
DISPLAY_MEMORY 

subcommand 9-52 
DISPLAY_PROGRAM_VALUE 

subcommand 9-57 
DISPLAY_REGISTER 

subcommand 9-65 
DISPLAY_STACK_FRAME 

subcommand 9-68 
DISPV subcommand 9-57 
DISR subcommand 9-65 
DISSF subcommand 9-68 
DIV operator 5-3 
DIVIDE.FAULT break 9-78 
Division operation 
Integer quotient 5-3 
Real quotient 5-3 
Remainder 5-3 
DSP, see Dynamic space 

pointer 
Dynamic link pointer F-4 
Dynamic space pointer 

(DSP) F-3,12 
[Dynamic variable F-3 



E 



Efficiencies G-l 
EJECT directive 8-15 
Elements 

CYBIL-defined 2-i 

Scope of 2-10 

Syntax of 2-8 

User-defined 2-3 
ELSE 5-27,29 
ELSEIF 5-27 
Empty statement 2-9; 5-15 
END 5-19 
Entry point A-3 
Equal to operator 5-7,10 
Equality, set 5-11,14 
Equivalent types 4-3 
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i-xapuj nopnnjaa aSBtiSuBq iigjto 



^ aoisiAay 



T6-6 aanaaooHd 

06-6 amaoi\[^LNaHano$ i 
06-6 3Nn~i,Naaano$ 

Z-9 HVHO$ i 
03-9 S«TlPO ! 

sz-9 ssaaaav# ! 

suorpunj ; 
patiTjap-jasri osp3 aas 'suopourtgl 
ft-S ^uijog 

;uauia^B?s ggygj 

9Z-9 spop 
puooasoaoira Sinuutu asag] 

92-9 uorpimj , 

HOOio _ ONiNNna _ aaaa#l 

IS'82-8 ssiduiBxg . 
28-8 S3AT403.IT.Q | 

93'T-8 aopduossa | 

62-8 puBairaoQ J 

apoo aojnos 2u.iWBTu.iogj 

92-8 1I9A0 'JSWBuijo^ 

62-8 puBraraoo] 

aoanos "iihao "ivwHoai 

9 }BTXIJOg; 

91-3 an^BA 

Sl-g aouajajay | 

Ql~Z uieaSoij 

Sl'll-L ajnpaoojj 

8X'9l-9 uoipung 

saa^auiBJBd [Buuogj 

oz-s aNaaoa! 

03-s iBuuog ■ 

22' 12-9 ssTdurexg 

02-9 uopraijaa 

^uaxaa^B^s HOd 

gg-8 aAipsjip jj^g 

6i-6 ^Baaq aOMVOMINOIS 

~XNIOd~ONLLVOia 

6L-6 ^aaq aj,iNiaaaNi 

"iNIOd'DNLLVOia 

Z\-f sdAj, 
g-2 ^uB^suog 
amod-BuxaBOT 
8fr'i-t sad^i pexrg 
6'9-a a «nuj 
■spB^s jo ;jBd azis-paxig 

3-a azTS 
2-g ^uarauSny 

laTTimrf aATiTSiai navrj 
— "t— i — — :t~i — i ria. 



Z-3. a z?S 
2-g ^uauiuS^y 
aa^utod paxig 

f-V -6Z-* PPM 

f--8 2utJ.STl 'SDT^SOuJBTp p3^Bg 

i-t ' asiva 



g-g aiqBtJBA 
paou3jajaa A^BUJS^xg 
8-8 '2T-Z 3iqBUBA 
psiBpap ^tjBUja^xg 
9X-8 ajsi^bs 'saouajsjaa p3uaa^xg 
LT-a S3DU3J3J3J [Buja^xg 
f?-y aouaaajaj {BtLia^xg 
X-g sjo^Bjado 
X-g spuBjado 
fr-V ^X-S uopiuijaa ! 
i-Z ^ubisuoq 
5-8 auit^-a^iduioQ 

uoissajdxgi 

_62,-6 ipwqj 

MOiaaaaNii tLNaNOdxa: 
MoiaaaAO "XNaNOdxai 

9-g ^uauodxgi 

8t-a Pt 9 U puBdxgi 

08-8 s^uamaws }txgj 

88-g ^Buuog ; 

^-8-9 3lduiBxg 

88-9 uopiuijaa 

^uauia^B^s xixg 

23-6 SuiSSnqsp 

'J0JU3 auti^-uopnDaxg 

^-y srap uoi^nDsxg 

fr-y Suij uonnoaxg 

8L-6 5[B3aq Noiinoaxa 

X-8 aopnoaxg 

9-c uouBjado yo SAisnpxg 

S-v ;« 3 Ag 

22-6 apoo 

3a:spod Smssaooad jo,ug 

^-8 suoi^do ja^xduioo ;sii aoxig 

XX-t saSuBjqns 

to SiiT-Hnaiin imiCT 
j*" — 7i 1- a. 



suoponnj paugap-jasfi osp oas 'suoiputijj 



saSnBjqns jo Sunjoaqo jojjg 



#GATE attribute 


Integer 


$CURRENT_PVA 9-91 


Default 3-12 


Data conversion 6-1 


Definition 4-46 


Definition 6-1 


Example 5-38 


Format 6-15 


Format 4-47 


$INTEGER 6-3 


Management 5-35 


#LOC 6-4 


Size E-15 


LOWERBOUND 6-4 




LOWERVALUE 6-5 




#OFFSET 6-27 
Overview 1-3; 6-1 


I 




Parameters 6-15 




PRED 6-6 


Identity operation 5-4 


$PROGRAM_ VALUE 9-92 


Identity, set 5-11,14 


#PTR 6-7 


IF statement 


#READ_REGISTER 6-30 


Compile-time 8-10 


$REAL 6-8 


Definition 5-27 


Recursive 2-11; 6-1; F-1,5 


Examples 5-28 


#REL 6-8 


Format 5-27 


#RING 6-31 


IFEND 5-27 


#SEGMENT 6-32 


Improper subrange type 4-10 


#SEQ 6-9 


IN operator 5-7,10,14 


#SIZE 6-10 


Indefinite value 


Standard 6-1,2 


constructor 3-14; 4-26,38,42 


STRLENGTH 6-11 


Inequality, set 5-11,14 


SUCC 6-12 


Informative diagnostics, 


System-dependent 6-1,24 


listing 8-4 


UPPERBOUND 6-13 


Inhibit code optimization 7-32 


UPPERVALUE 6-14 


Initializing 


User-defined 6-15 


Array elements 4-26 




Effect of attribute on 3-16 




Record 4-38 


G 


Set elements 4-42 
Variable 3-4,14 






T"NTT TXTT^ — J.J :i i-_ /»-■/» i-r t i 




iiiuiiiii aLLiiuuue o-io, (-11 


#GATE attribute 3-4; 6-16; 7-11 


[nline functions 6-16,22 


Global variable 2-11 


Inline procedures 7-11,18 


Glossary A-l 


Input 


Greater than operator 5-7,10 


Compiler parameter 8-2 


Greater than or equal to 


To programs 1-4 


operator 5-7,10 


Input file, Debug 9-6,28 




Input/output 5; 1-4 




Integer 


H 


Alignment E-2,3 




Constant 2-5; A-4 




Definition 4-5 


#HASH_SVA procedure 7-26 


Example 4-5 


Heap 


Format 4-5 


Adaptable 4-53 
Alignment E-15 


Quotient division 5-3 
Range 4-5 
Size E-2,3 


Allocation 2-12 
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6-xapuj not^iugaQ aSmSireq qigjto 



^ uoisiAay 



9-V 



333 



81-8 37WWO0OM 

n-8 aiidiroo 

[0J:}U03 aDUBU9}UTBJ\[j 

SuiSSnqgp i9A9{-9UTqDBj\[| 

^imn snqaa 

'SuiSSnqap apoo aunpBj\[j 
g-y 3urss9jppB aunpBj\[j 





HI! 




j 

9Z-L uorpruqsui goVdlj 


S-9 


uoppunj amVAHaMOl 




OX-t spunoqaa^oq 


t-9 


uo^Dunj aNnoanaMoi 




3-g uopBJ9do jjo l B °|3oq 


g-g uopBJ9do QjsfV IBOiSoq 




Z2-Z, aiqetJBA spoq 




OZ-i, sptaxj jpoq 




Ol-g aiqBUBA iBDoq 


8-a 


9[qBUBA DUBrao^nB [BOOq| 




[Booql 



7 -y uui+juiy. UU' Iff 

A'l'O AOirapijp auii^-pBoqi 

9g-i X9pui 9[qB^ aSBd pBoqj 

g-y 9{npoui pBoq; 

2T-S uotpas lVH3Xn$l 

tg-8 9i§scn raoxsn 

Xg"8 sa^So^ Supsri 
g-g jg^gtaBaBfj 
g-8 suoi^do 
jafiduioo '3m%syi 

ig-8 9iiS(xj ixaisn 

Ig-8 91230} SiOJ,Sn 

12-8 9i33(4 TiViLSn 

X2-8 9\S2o% xsn 

9-q apnpora paspirj 

^-8 sajqB} autq 

nT-g aiqBiJBA b jo aurpjajrr 

91-8 pjooaj AXBjqiq 

9i-8 aAi^oajip Aavaan 

:JI'ZT"8 aAi?09orp ioj;uoa iCrejqn 
9X-8 ioj^uoo AiBjqri 

OX'L'S ao^BJodo 
oi TBtibg jo UBua ssga 



QVL-Q JO^BJ9do ireq} ssaqi 
9g-8 Sui^Btujoa j 
2X-8 9uiT^-9iidrao3 

aAipajip ijgq; 

SZ-8 aiiLL ! 
SZ-8 ONIOVdS i 

tz-8 diss 

8Z-8 iHOm j 
81-8 ailLLCHO 

ii-8 aixii^aN ' 
sx-8 xaai ! 
9i-8 loafa 

gX-8 saAi^oaaip [oa;uoo ^noABq] 

9X-a uaaM^aq sipo 'saSBtiSuBq! 

8-2 xbhias 93Bn3uBqj 

IS'f'Z'SZ'OZ'et-Q }U9ra9}B^s ; 

'pqBq 



2,2-2, ajnpaaojd XNIOdAaM#! 

2,2-2, uorptuEjsui %modA.9yft 

OZ-L spiag ^aoyXa^! 




Og-t ?Buuoa 

2g-t aidraBxg 

Og-t uopnnjga 

pjO09J ^UBIJBAUI 

62.-6 ^eajq 

vxva~daa~anvANi 

g-g }9S 'U0T}39SJ9}UI 
gX-g U0pBJ9d0 U0T^39SJ9}UT 

2.X-6 3nq9Q 
'Sinss9DOjd ^drujaitq 
g6-6 9tdraBxg 
t-y uoi^ruTjaa 
SnqaQ aAipBja^ui 

C-Q UOTlOtmi WKWTATT* 



saAipajip jozmoo aowBua^aiBj^ 



uotpunj HaD31NI$ 



Manuals 



OR operator 



Manuals 

Online B-l 

Ordering B-l 

Related B-l 
Manuals, related 5 
Map buffer, purging 7-28 
Margins, set 8-15,23,31,36,37 
Maximum save area F-8 
MAXINT H-3 
MAXLENGTH function H-3 
Memory 

Alignment of data E-l 

Cell E-l 

Change contents during 
debugging 9-30 

Data in E-l 

Display during 
debugging 9-52 

Examples of data in E-l 6 

Packed data E-l 

Size of data E-l 

Unpacked data E-l 
Minimum save area F-8 
MOD operator 5-3 
MODEND format 2-13 
Module A-5 

Addressing A-5 

Declaration 2-13 

Definition 2-10 

Examples 2-14 

Format 2-13 

Level 2-11 

Name 2-13 

Structure 2-10 
MODULE format 2-13 
Multiple breaks 9-21 
Multiplication operation 5-3 
Multiplication operators 5-2 
Multiring environment 9-21 
Multitask debugging 9-17 



N 



Name 

Definition A-5 
Examples 2-3 
Rules for forming 



Nearly exhausted 

resources 9-18 
Negation operation 5-13 
Negation operators 5-2 
NEWTITLE directive 8-17 
NEXT statement 
Definition 5-41 
Format 5-41 
NIL pointer constant 2-6; 4-15; 

E-5 
No-op instructions 8-5 
NOCOMPILE directive 8-18 
Nonlocal exit 5-33 
NORMAL field 9-8 
Not equal to operator 5-7,10 
NOT operator 5-2 
Null string 2-7 



o 



2-3 



Object code 

Definition A-6 

Listing 8-3,21 
Object library control 

directive 8-12,16 
Object module A-6 
Object of a pointer 4-13 
Offset, byte A-2 
#OFFSET function 6-27 
OLDTITLE directive 8-18 
Online manuals B-l 



r\ ]- 

upci anus 



Operators 

Addition 5-5 

Definition 5-1 

Multiplication 5-2 

Negation 5-2 

Order of evaluation 5-2 

Relational 5-7 

Set 5-12 

Sign 5-4 
Optimization compiler 

options 8-5; 9-16 
OPTIMIZATION. LEVEL 

parameter 7-32; 8-5 
Optimization of code 7-32; 
Optimized code, debugging 
OR operator 5-6 



8-5 
9-16 
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Xt-xapiq noRjuyaa a3wi3HBq ng^o 



^ UOISIA&H 



91-L 3m\yeo j 

OZ-L ai~H3TIVO# ; 

sa.mpaoo.id j 

jainjap-aasfx osjb aas 'sajnpaDOjji 

ZT't-J (VSd) ! 
ja^uiod b3jb 9abs snoiAaJtjJ 

gg-9 uorpimj | 

vaav~aAvs - snoiA3Hd#l 

83"9 bojb babs snoiAajjj 
2X*S suoi?D8S pauTjapaijj 
9-9 uoissajdxa 
ub jo jossaoapaajj 

9-9 uo^ounj aaad! 

9-V dd 
£-f sacLfy ^uap3Amba A"[p3rjua;0(£ 

61-8 aAppajip dOd 
QZ'L ajnpaooad 
uoTSjaAuoo aanpaDoad-o^-ja^uptj 
2\-f uopnnjaa 

gg-9 uotpunj ssaaaav* 

[{3D 0% ja^OTOjJ 

g-g aouanbas oj, 

6-g ampaooad ox 

8-3 pjooaa iubijba punoq ox 

9I-t oi^S 

s's-a 9ZIS 

LZ-9 (Jaquinu 

a^Aq) ^asjjo pauSxg 

SS-9 ;uaui3ag 

18-9 Suia 

28-9 -laquinu ;uauiSas uotnay 

18*9 J9q™nu Suij uan^ay 

OT-a -6X-t 3A^Biaa 

gX-t aouajajay 

8i-t 1193 o^ Ja^utoj 

2,2-9 uorpunj xasadO# 

8i-t peftO 

9-3 -9I-t 1IN 

f>-g UOrpiItlJ ooi# 

2X-t ^buijo^ 

^x-^ aidnrexg 

gX-t aouajajajaQ 

9-V ; ZI-t uorjnnjaa 

9-g lUB^SUOQ 

2,2-9 jaqainu a^g 

8I"t 3uiu3issy 

9'S-a ^uamuSiiv 

9X-t> sadX^ a^qB^dBpy 

aa^uTOj 

00 u -t r — i"-xi 



LZ'L 8uuo:nuoui aouBrajojaaj 
8X-6 ^ sj q astiBj 
^X-a saa^araBJBd Buissbj 
X-fj saauajajjtp 

1I3AO P UB lB3SBd| 

8'i-9 '61-fr 3IIIBU ^ua^d 
2,x*a saoaja 
uox^BOTjijaA ja;araBJB<j 

2X-8 aopoas Hai3HVHVd$ 

?l-£ SuxssBd ja^auiBJBtj 

8I-i ; 8I-9 ; SX-3 ?sn ja^aoiBJBdi 

aiqB^ I 
aSed uia^sXg aas 'ajqBt aSB^i 
82-2, dBui a^qB^ aSB^i 
QX-8 aArpajrp aouBApB aSBjj 
9-V aSB^i 
g-8 ja^auiBJBd janduioo SuippB<j| 
gg'Og-* spaooay 
92-f sA*Bxry 
xg-t spjooaj ajqB^dBpy 
Qf-f sA"bjjb ajqB^dBpy 
02-t aa^auiBJBd SunpBj 
S8'0S-t spjooay 
92-^ sA*Bxiy 
Xg-fr spaooaj ajqB^dBpy 
6^-^ sa*bxib a^qB^dBpy 

aa^auiBJBd aaaovd 

X-g A"aouiaui 
in s^uauta|a pa^oBj; 
99-6 ^BidsiQ I 
68-6 aSuBqo 
ja^si3aj j 



X-x aSBiiSuB^ jo MaiAaaAO 

f-\ suiBjSojd uiojj ^nd^no 

8Z'i-6 StiqaQ 'axtj ^nd;no 

i-6 3 lL r .LTMinO* 

f'Z-3. aziS 

8-t ^Bimoa 

g-^ S3[duiBXa 

8-t uoi^iinjaa 
g-2 ^ub^suoq 

(BUipJO 

t"9 spanuBui SuuapjQ 



ssjnp330jd partgap-aasfi osp aas 'sajnpaoojj 



norpunj gaO 



PROCEND format 



$REAL function 



#COMPARE_SWAP 7-22 

Definition 7-1 

Format 7-10 

#HASH_SVA 7-26 

#KEYPOINT 7-27 

Overview 1-3; 7-1 

Parameters 7-10 

#PURGE_ BUFFER 7-28 

Recursive 2-11; 7-1; F-1,5 

#SCAN 7-30 

#SPOIL 7-32 

Standard 7-1,2 

STRINGREP 7-2 

System-dependent 7-1,20 

#TRANSLATE 7-34 

User-defined 7-10 

#WRITE_REGISTER 7-37 
PROCEND format 2-16 
Process register 

Read 6-30 

Write 7-37 
Process virtual address 2-6; 

6-27; 9-91; A-6; E-5 
Processor register 

Read 6-30 

Write 7-37 
Program 

Addresses in Debug 9-10 

Declaration 2-15 

Elements 2-1 

Example 2-16 

Execution 8-1 

Format 2-15 

Input 1-4 

Name 2-15 

Output 1-4 

Structure 2-10 

Syntax 2-8 

Value, change 9-34 

Value, display 9-57,92 
PROGRAM format 2-15 
Program level 

specifications 9-4,5 
$PROGRAM_ VALUE 
function 9-92 
rograrniiiing 
recommendations G-l 
PSA, see Previous save area 

pointer 
#PTR function 4-19; 6-7 



Punctuation 2-9 

Purge 

Cache 7-28 
Instruction 7-28 
Map buffer 7-28 

#PURGE_BUFFER 
procedure 7-28 

PUSH directive 8-20 

PUSH statement 
Definition 5-45 
Example 5-38,45 
Format 5-45 

PVA, see Process virtual 
address 



&. 



QUI subcommand 9-74 
QUIT subcommand 9-74 



iR 



Radix 2-5 
Range A-6 
Range checking 

Compiler options 8-6 

Toggles 8-22 
READ attribute 3-3,6 
READ break 9-79 
READ_NEXT_INSTRUCTIQN 

break 9-80 
Read-only 

Section 3-6,12,20 

\T 4„U1_ O O O 

v <xi iciuig o-u,u 

#READ_REGISTER 

function 6-30 
Real 

Alignment E-2,4 

Constant 2-5 

Definition 4-12 

Format 4-12 

Quotient division 5-3 

Range 4-12; E-4 

Size E-2,4 
$REAL function 6-8 
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SX-xapui uomtnjaa aamSireq qjgAO 



$ uoisiAay 



St'SS"9 ^traraaSBUBtn 
^jdb^s aun^-uny 
3X-3 uot;bdohv 
ipB^s aun^-uny 
arai^ uoxpioaxg aas 'aan:j urvjj 
X-a ^uauiuanAua auip-uny 
Sg-8 sai§§ox 
9-8 suorjdo jajiduioo ' 
Suppaqo 3rap-un?j| 
92r6 puBuiuiooqns jsjfia 
9-g jaqumu Suxy 
Xg-9 uorpunj ONIH# 
y-y uopnoaxa 'Suiy 

Xg-9 ja^tnod 

ut jaquinu uarnay 

OZ-L '9Z-9 -isqxnnM 

i-V uopiuijaa 

6X-6 SnqaQ 

ig-8 Sui^bhijoj 
gg-8 amp-aiTdmoo 
a A poaaip iHOIHj 

f?g-g 4tsuIaO^ 

frg-g uopraijaa 
luauia^s NHfliaHl 
gg-g aouanbas b joj ^Buuoa 
0^-g dsaq b joj ibuijoj ! 
8g-g aidinBxg 

68-S uowuijaa 

;uauia;B;s X3S3H 

32-8 aArpaatp xasaH 

I-a -2,-V -I-Z spjoAi paAaasay 

g-g s[oqm^s paAjasay 

OX-6 sassajppB pa^aoday 

gg-g ^Buuoa 

gg-g ajdurexa 

SS-9 uopiurpa 

luaraa^s ivadSH 

9Z-t -9I-S JBdijoj jsh 

g-g uorjBjado 

uotsiAip lapuiBuiaa 

OX-3 aouanbas 
o? aa^uiod aApB^a^j 

0X _ 3 P-I003J JUBIJBA 

ounoa m jaitnod aAiiBTau 



oi-a 3zts | 

8-9 uan^ay 

8-9 uoppunj qga# | 

L-9 notjounj aid# j 

6X-t ^Biuaoa | 

6X-t aa^uiod paaiQ j 

6X-fr uopiuxjaa 

6X"t J9^uiod 

paoip o% Bui^jaAUOQ 

OX-a ;uaoiuEi{V 
i-9 jo :pafqo ssaaoy 

la^uiod 3ApB(a^j| 

2,-g sao^Bjado [BuopBja'jij 

I"9 -9 sjBnuBui pa^Bia^j] 

8-9 -6I-t uoxpunj qaH#l 

L2-L ^«M i 

08-9 P^H 

gg-6 ^BidsiQ 

68"6 J° s^ua^uoo aSuBqg 

3X-a s^uarauifrssy 

sja^siSay 

ZI-S uorpas H3.LSID3H$ 

8Z'l"8 8 P oa 33-mos ^Buuojay 

gX-6 sassajppB paouaaajay 

gX~t aajuiod 'aouaiajay 

9X-g oiBjSojtj 

ST'Zl-L ampeoojj j 

yX'd §UISSB(J 

8l'9I-9 uopouna 
sia^auiBJBd aouaaajayj 

9'i-a '1-2, ' 
!X"9 -XT-3 sajtipaooad/suotpunj I 

aAtsjiiDagl 

Q'l-d -I-A -1-9 -II-Z uoisatiDaai 

8S-t ;u^ JB A 

2T'2-a azjS 

6g-t s^uaraap Supuaaaja'a 

08"^ ^ubtjbaui 

8g-f s^uaoiata Sutzipapxui 

88'08-t ^uuoa 

6Z-f spiaxa 

GS'SS'iS'ZS-t sa^duiBxa 

QZ-f uopiinjaa 

9S'S8-t 1«btjba punog 

Sl'S-3 

•X9'0t>8'08-^ ^uarauSiiV 

I9-t aiqB^dBpv 

pjooay 
X-£) SuiuituBjgoad 
'suoxiBDuauiniooa'u 



^uaraaSBUBui jpeqs auin-nn^ 



SuratraBiooad 'snouBpnaniraoD^g 



Save area 



SPACING directive 



Save area 6-28; F-2,8 
Scalar types 4-4 
#SCAN procedure 7-30 
Scientific notation 2-5 
SCL A-7 

Scope attributes 3-8 
Scope of elements 2-10 
Section 

Attribute 3-4,11 

Declaration 3-20 

Definition 3-11,20; A-7 

Example 3-21 

Format 3-20 

Name 3-4,11 

Predefined names 3-12 
SECTION format 3-20 
Segment 

Definition A-7 

Number 6-25; 7-20 

Return number in 
pointer 6-32 
#SEGMENT function 6-32 
Segment number 2-6 
Segment table map 7-29 
Semicolon 2-9 
#SEQ function 6-9 
Sequence 

Adaptable 4-53 

Alignment E-15 

Allocation 2-12 

Definition 4-44 

Format 4-45 

Management 5-35 

Pointer to E-8 

Relative pointer to E-10 

Return pointer to 6-9 

#SEQ function 6-9 

Size E-15 
Set 

Alignment E-14 

Complement 5-4,13 

Containment 5-14 

Difference 5-5,13 

Equality 5-11,14 

Identity 5-7,11,14 

Inclusion 5-14 

Inequality 5-7,11,14 



Intersection 5-3,13 

Membership 5-7,10,14 

Negation 5-13 

Operators 5-12 

Size E-14 

Subset 5-7,11 

Superset 5-7,11 

Symmetric difference 5-13 

Union 5-5,13 
SETLBREAK subcommand 9-77 
SET directive 8-24 
SET_STEP_MODE 
subcommand 9-86 
Set tabs 8-34,35 
Set type 

Alignment E-2 

Assigning elements 4-42 

Definition 4-41 

Example 4-43 

Format 4-41 

Initializing elements 4-42 

Size E-2 
Set value constructor 

Definition 4-42 

Format 4-42 
SETB subcommand 9-77 
SETSM subcommand 9-86 
Sign inversion 5-4 
Sign operators 5-4 
Size 

Data in memory E-l 
Size fixer 5-37 
#SIZE function 6-10 
i>Kif directive 8-24 
SL, see Static link 
Source 

Code A-7 

Listing 8-3 

Text input 8-2 
Source code 

Compiling 8-1 

Efficiency G-l 

Formatting 8-1,26 
Source code debugging, see 

Debug Utility 
Space allocation F-1,17 
Space compression 8-30,33 
Spaces in syntax 2-8 
Spacing 2-9 
SPACING directive 8-25 
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St-xapuj uorjiuyaQ aSsnSuBq ngjto 



J U0ISIA9JJ 



8I-S MaiAjaAo 
OZ-9 H(M 

6i-s Nioaa 

siuauia}B}s pajiupoqg 

IX-9 uorpunj HlONaiHiS 

g-2, ^uauiaja aSuBjqng 

g-2, luatnaja Suu^g 

Q-l ;uauiaja ja^mo^ 

9-i ^uaraaia psmpjo 

f^i luautaja jaSaiui 

9-i ^uauiaja iinod-BupBoia 

2-i uopxmjaa 

g-2, ^uaoiaia ja^oejeqQ 

g-/, ^uauiafa uBajoog 

ajnpaooid daHONIHlS! 

IZ-t 'L"Z SuiJ^sqng 

1 1-9 uopounj HXDNaiiLLS 

II'S-3 az?S 

IX-9 iflSuaq 

OZ-t iBtuaoj 

frZ'SZ"t saidurexg 

Og-f uopiuijaa 

L-V -9-Z ^ub^suoo 

9-3 UOI^BUa^BOUOQ 

fg-fr 3uiJBduioo 
fZ-f SuixiStssv 

6^-t atq^dBpy 

3uu;si 
ZI-Z uopBOo^v 
^t-fr sadA} aSBJO^gi 

6s-s xasaa 

9f-9 HSHd 
gg-g MaiAjaAO 

Ifr-S iX3N 

n-9 aaaa 

88-9 saidutBxg 

zt-s axvocmv 

s^uaraajB^s 

juaraa§BUBin aSBaoig 

6-g sa^nqu^B aSBJO^g 

il'l-a 'Zl-Z aoi^BoonB aSBj(ng 

9g-g SnqaQ 'apora 6.9x9, 

Xg-8 pUBUIUIOO 

aoanos - iiaAO _ ,ivPiHoa 

8-6 BnqaQ 
i-8 puBuiraoo qiaAO 
^-8 HBO jandraoo 
aiaBUBA sniBia 



S-a -6-S : ZI"Z aiqsiJBA Di^gj 

ZX-g uotpas OLIVIA 

9X-t sja^uxod ax^B^gi 

ZlVa -6-3 (IS) ^FH 3FWSI 

OlVS ; ZX"Z ^nqu^B QixviSi 

frZ-S 31IHM 

gl-g pa,miDiu:;g 

gg-g ^uaraaSBUBui aSBJO^g 

ts-9 Nani,aa I 

6s-s xasaa : 

2Z-9 ivadaa i 

9t-S HSIld 
g-X maiAjaAO i 
lf-9 - !X3N 
i-V : 8T'SX-S jsn 

xsWsz'oz'ex-s pqwi 

az-s ai 

tt-s aaaa 

oz-s aoa 

88-S nxa 

SX-9 -6-S Aduig 

gx-g uopiuijaa 

xs-s aaoAO 

93-g loa^uoo 

9-8 UOI+BLiduIOQ 

6z-s asvo 
61-s Nioaa 

gx-g juarauSissv 

z*-s aivocmv 

(s^uauia^g 

Z'X _ i sampaaojd pjBptre^g 

Z'X _ 9 suopatmj pxepuB^g 

amBJJ 3[3B^g pus 

jjdb}s arap-uny osp3 aas '^OB^g 
ZX-S aopoas HOVJLSS 

8Z"9 B9aB 3ABS 3QIBJJ 3J3B}g 

89"6 ABjdsrp 'auiBjj 3pB}g 
Il'9-3 vsd azis-aiqBTJB^v 

8'2-J B3JB 3ABg 

A'S-a ^uuoj 

g'9-a ^jBd azis-paxia 

g-a asn jo a^dtuBxa 

6-d B9JB ^B^dSTQ 

X-a aondTJDsaQ 

8Z-9 -ZX-Z staB-iJ ^a^S 

ajqB^ a§Bd uia^s^g aas '^jg 

7P-; amttaooid amjojt 



s^uauia^Bis paituDtu^g 



ampaooad iiodS# 



Structured types 



Types 



REPEAT 5-23 

WHILE 5-24 
Structured types 4-20 
Subrange 

Alignment E-2,4 

Definition 4-10 

Error checking 4-11 

Example 4-11 

Format 4-10 

Size E-2,4 
Subscript bounds 4-25 
Subset of a set 5-7,11 
Substring 

Definition 4-21 

Examples 4-23 

Format 4-21 

Of a string constant 2-7 
Subtraction operation 5-5 
SUCC function 6-12 
Successor of an expression 6-12 
Superset of a set 5-7,11 
SVA, see System virtual 

address 
Symbol tables 8-4 
Symbolic 

Addressing A-8 

Cross-reference listing 8-3 

Debugging A-8 
Symbols, reserved 2-2 
Symmetric difference 5-6 
Symmetric difference 

operation 5-13 
Syntax 2-8 
System-dependent 

Functions 6-1,24 

Procedures 7-1,20 
System page table 7-26 
System virtual address 7-26; 
A-8 



Tab settings 8-34,35 
Tag field 

Definition 4-35 

Size 5-37 
Terminate break 9-18 
Text-embedded directives 



8-1 



TEXT field 9-8 
TITLE directive 8-25 
Titles 8-17,18,25 
Toggle control directives 

Definition 8-12 

Listing toggles 8-21 

POP 8-19 

PUSH 8-20 

RESET 8-22 

Run-time checking 
toggles 8-22 

SET 8-24 
Traceback A-8 

#TRANSLATE procedure 7-34 
Translation table 7-34 
Trap interrupts 7-27 
TRUE 4-7 
Type 

Declaration 3-18 

Examples 3-19 

Format 3-18 
TYPE format 3-18 
Types 4-1 

Adaptable 4-48 

Adaptable array 4-49 

Adaptable heap 4-53 

Adaptable record 4-51 

Adaptable sequence 4-53 

Adaptable string 4-49 

Array 4-25 

Basic 4-4 

Boolean 4-7 

Cell 4-12 

Character 4-6 

Equivalent 4-3 

Fixed 4-1,48 

Floating-point 4-12 

Formats for using 4-2 

Heap 4-46 

Integer 4-5 

Ordinal 4-8 

Overview 1-1; 4-1 

Pointer 4-12 

Pointer to cell 4-18 

Potentially equivalent 4-3 



xtea* 
Record 4-29 
Relative pointer 
Scalar 4-4 
Sequence 4-44 



4-19 
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iX-xapui uotjiuyaa a3im3uBq nas.0 



& uoisiAay 



t-8 



ts-g jBraioa 
92-9 ajdurexa 
fZ-9 uopratjaa 
luaraaqBis aiiHM 
SuT^sii 'sotjsouSBip Sutoubm 



AV 



gg-^ ^Btaaod 

12-f aidraBxg 

gg-t uoT^iuijaa 

98*88"* punog 

paoaaj ^ubub^ 

lX'9-d a^Bjj 

ipB^S JO ^JBd aZIS-ajqBIIBA. 

H-,g uopBOOfiB aiqBUBA 
E-tf '6-S -2X-Z =>TWS 

9'g-g i?lUO-pB8H 

g-a opBuio^nB [Booq 

OX-Z t^ooq 

OX-S srat^ajiT 

tX't'S "OT? 52 !!^™! 

XX'-Z FqoiO | 
g-g ^BUUO^ | 

ZJ'SX'XX'6'Z/S-e satdaiBxa 
g-^ annBu^a 
8-V : 8-8 uopiuipa \ 
g-g uo^BOBpaa | 
8-g auip-aiidraoQ | 
S"d -6-8 : XX-Z apBoienny \ 
8"V : 9'8"8 sa^nqmiy 

ajqBUBAJ 

g-g iBUUoj hva; 

9X-g uibjSojj 

SX'ZX-2, ajnpaaojd 

f\-& Sutssbj 

8X'9X-9 uorpuna 

SJ9^9UIBJBd 9n[BA 
JOipTU^SUOO 9tip3A 

g^niTjapuj aas 'aapru^suoo 9np3A„ 



H-a 

tPT'ZT-A SJ919inBJBd 9TITBA 



■SX'ZX-A sja^auiBJBd aauaiajay 

8X'0I-A saa^auiBJBj 

8X'XX-i 9«TPI 

OX-L ^Buuojj 

SX'XX-Z, sj9}9raBJBd iBuuoa 

9X'H-£ s9idraBxg 

9X-L SxniiBO 

Ox-L ss^nqij^v 

SX'SX-i sj9^9uiBJBd pmpy 

S9.Itip9D0.ld p9UIJ9p-J9S{l 

•8X'9X-9 sja^auiBJBd 9np3A 

•8X'9X"9 sjajauiBJBd gougjajgy 
8X'SX"9 saa^auiBJBd 

3S'9I-9 3"H U I 

9X-9 ;buuOjI 

8X'9X _ 9 sja^guiBJBd peauoa 

XZ'6X-9 s9iduiBxg 

02-9 3uinBQ 

9X-9 sa^nqu^y 

02'8X"9 si9i9aiBjBd psivpy 

suotptmj pauy9p-j9Sfi 

g-g S9UIBM 

g-g uorjraijgQ 

g-g SJUB^SUOQ 

l-Z suoissaadxa ^ub^suoq 

siuauiaja pauijap-jasf^| 

n-9 uopounj aniVAaaddni 

0X-* spunoqjaddqj 

gx-9 nocpnnj aNnoaaaddh 

PZ-C TTTATH 

X-a Ajoinara 
in s^uaraaja p95JDBdufX 
g-g ;as 'uonifi 
gX-g uox^Bjado uoiufx 
gg-2, ajnpaaoid 

NOisaaANOO~aaHoaHONn# 



ft 



0X"t 9SuBjqng 
Og-t p9Jtnoiu?g 

Tfc-* 19G 



ingura^s aaiHM 



aonpaaoad N0ISH3AN00 aaa03H0Nn# 



WHILE ND 



XREF attribute 



WHILEND 5-24 
Word-aligned E-3 
Words, reserved 2-1; A-7; D-l 
WRITE break 9-80 
#WRITE_REGISTER 
procedure 7-37 



X 



X registers 

Change 9-39 

Display 9-65 
XDCL attribute 2-12; 3-3,8 
XOR operator 5-6 
XREF attribute 3-3,8 
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86 19-93 1 S9 KW <S IITH napjy 
anuaAV uo^inxaq *^ 103^ 

6IZHHV 
uotsiatq suopeoixqn^ # £?o{ouqoax 

VXVQ 10HXN03 



aassanaav ah aiva aa tiim aovisod 



iivw Aidaa ssaNisna 



saxvis aaiiNn 

3H1NI 

aanivwai 
AHvssaoaN 
aovxsod on 



ioa 



•ijuo adsq. i^im sa2pa [Ba 
!autl paw°P °o PI°J asBat, 



(apis jatpo mojj pamnquoo) sjuararaoQi 



CYBIL Language Definition 60464113 F 

We value your comments on this manual. While writing it, we made some assumptions 
about who would use it and how it would be used. Your comments will help us 
improve this manual. Please take a few minutes to reply. 

Who are you? How do you use this manual? 



p Manager p As an overview 

P Systems analyst or programmer p To learn the product or system 

P Applications programmer p For comprehensive reference 

D Operator p For quick look-up 

3 Other 



What programming languages do you use? 



How do you like this manual? Check those questions that apply. 



Yes Somewhat No 

D □ P Is the manual easy to read (print size, page layout, and so on)? 

D P P Is it easy to understand? 

DPP Does it tell you what you need to know about the topic? 

O D P Is the order of topics logical? 

DPP Are there enough examples? 

D D P Are the examples helpful? (P Too simple? D Too complex?) 

D P P Is the technical information accurate? 

ODD Can you easily find what you want? 

D D D Do the illustrations help you? 

Comments? If applicable, note page and paragraph. Use other side if needed. 



Would you like a reply? p Yes p No 



From: 



Name Company 



Address ~ Date 



Phone 



Please send program listing and output if applicable to your comment. 
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fZ-9 




' " 31IHM 


f£-9 ' 
6£"S ' 
Ofr-S ' 


■ • • (cteeq 


• ' Naiuaa 

* u i) lasaa 
B u t) lasaa 


82-S 




' xvaaaa 


9t"9 




• • ' • Hsnd 


1^-9 




" ' ' " J.X3N 


LZ-9 ' 




ai 


ff-9 




Ltlidci^l 


OZ-S 




aoa 


88-9 




■ nxa 


xs-9 ' 




' ' ' aiOAO 


63-9 .' 




' asvo 


6T-9 




■ ' " Nioaa 
aivoonv 


91-9 
3^-9 





e-s 

8I-S 

01 ~f 

oz-t 

6t-t 

f-2 

9f-f 

bz-e 



xapuj ;u9ui3^B^g 



• avA ! 
adAJLi 



' ' (P 8X U) DNiaiSi 
(©tq^dBpB) ONiaiSI 

OliViSi 

(paxij) bas 

■ • (aiav.'idnrivA fana 

\"L"L" + \T ~ / \J\LLhJ 

xas 

Nonoas 

aaa 

laa 

• • • • cureuBA) aaooaa 

• • • (luBUBAui) aaooaa 

• • ■ (etq^dBpB) aaooaa 

ivaa 

Hvaooaa 

(unuSoad b joj) aNaooad 



tfr'St'9S-t ^91-8 
0X-t 

)8"t 
I9-t 
5I-t 
ST-Z 



01-2, 

01-i 
2I-t 
8-^ 
8X-2 

sx-s 

J r 

S9-* 
9X-9 
9X-9 
X-8 

sx-t 

L-f 
93-t 

6*-t 



■ ■ • (aanpaaojd 

* jo j) dNaooaai 
aa.Qaaooa<± 

jajuTOti! 

I BU TP J 

amaoM! 

' aNaaow 



■ • • ■ (paxij) JV3H 

• (8iqB;dBpB) d vaH 

' NOLLONna 

aNaoNna 

ISNOO 

avHO 

nao 

Nvaiooa 

• • (paxxj) Avaav 

(atq^dBpB) AVaaV 



xaput pjOMiCayi 



Function Index 



#ADDRESS ........ 6-25 

$CHAR 6-2 

#FREE_RUNNING_ 
CLOCK 6-26 

FUNCEND 6-15 

FUNCTION . 6-15 

$INTEGER 6-3 

#LOC 6-4 

LOWERBOUND 6-4 

LOWERVALUE 6-5 

#OFFSET 6-27 

PRED 6-6 

#PREVIOUS_SAVE_ 
AREA 6-28 



#PTR 6-T 

#READ_REGISTER . . . 6-3C 

$REAL 6-? 

#REL 6-? 

#RING 6-31 

7TOaJV4X*AXJIJ.T j. D-O^ 

#SEQ 6-£ 

#SIZE 6-1C 

STRLENGTH 6-11 

SUCC 6-15 

UPPERBOUND 6-15 

UPPERVALUE 6-14 

User-defined functions . . 6-l£ 



Procedure Index 




#CALLER_ID 


7-20 


#COMPARE_SWAP .... 


7-22 


#CONVERT_POINTER_ 




TO_ PROCEDURE .... 


7-25 


#HASH SVA 


7-26 


#KEYPOINT 


7-27 


r»r> nrrci t>t tt> n 


1-J.U 


PROCEND 


7-10 


#PURGE_BUFFER .... 


7-28 


-lLC*r\ A AT 


t-ou 

7-32 


#SPOIL 


STRINGREP 


. 7-2 


#TRANSLATE 


7-34 


#UNCHECKED_ 




CONVERSION. 


7-35 


User-defined procedures 


7-10 


#WRITE_REGISTER . . . 


7-37 
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-IT 
-II 

-SI 
-31 

^11 
-31 

31 

-II 

LTT 
i 1- 1- 

fix 

-II 



-II 
-II 
"II 



~AaVNia~NOLLISOd$dA0i 
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IVNIHHai 

~ojraaj,03NNoo 

~aiM$dAO! 

aaooaa I 

"IVLLHVd ~XaD$dAO 

3NH 

— TVT.T.WW.J- - .T CTn*J i ni. 



aaooaa 

"ixaN~,iao$dAoi 



-ii 
-ii 

-ii 

-31 
-31 

-II 

-II 

-II 

-II 

-II 

-II 

-II 

-II 
-II 



" 3Mn-|LXaN~J.af)JdA0| 

AavNia 

~xxaN~i,ao$dAO 

AavNia 

~aaAaH~xaD$dA3 

"aaiaiiiNaai 

"aaia'iaoSdAO 

aaiNiod'ana 

~AavNia - vLao$dAO 

■ ■ ■ aiuiraavaNvis 
"Avidsia$dAoj 

RLDN31 I 

~aovd~Avidsia$dAO 
j,oara 

~3OVd~AVldSia$dA0 

asawriN 

_ aovd~xN3aano$dAO 

MOIJDISOd 

"ana^Msaano^dAO 

SNlTAVldSia 

~XNaaano$dAO 

iMwmoo 

"iMaaano^dAO 

31I3~aSO10$dA0 

A3a~31I3~AaVNia$dA0 



xapiq aanpaoojj /I 1I9A0 



S3-8 
S3-8 
f3-8 
^3-8 

^3-8 
|)3-8 
01-8 
^1-8 
31-8 



SAtpanp ONIOVdS 
■ • aArpajip draS 

• • • 8Ai;390Tp J.3S 
• 9AR03Jip J,HOia 

• • 9Ap33oip iasaa 

• ■ 9Ap03Jip HSIld 

• ■ • aAtpaaip dOd 

aApDajip aijjjxrco 

9ATp9Jip aildHOOON 



Ll-8 

91-8 

9£'SI-8 

SS-8 

63-8 

91-8 

3-8 

H-8 

K-2 



9Apo9Jtp aixiiMaN 
9ApD9irp Aavaan 
• • 9AR09Jip xaai 

■ • • 9ApD9Jtp iJ^a 

pueuimoo aOHflQS 

~iiaAO~ivkaba 
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puBuiuioo HHAO 

9Aip9JT P aildHOO 
9ApD9Jip J,N31A[31O0 



xapnT nouHTidinon pub SumeuLio^ 



CYP$POSITION_ 
DISPLAY_PAGE 11- 

CYP$POSITION_FILE_ 
AT_BEGINNING 11- 

CYP$POSITION_FILE_ 
AT_END 11- 

CYP$POSITION_ 
RECORD_FILE 11- 

CYP$PUT_KEYED_ 
BINARY 11- 

CYP$PUT_NEXT_ 
BINARY 11- 

CYP$PUT_NEXT_LINE . . 11- 

CYP$PUT_NEXT_ 
RECORD 11- 



CYP$PUT_PARTIAL_ 
LINE 11 

CYP$PUT_PARTIAL_ 
RECORD 11 

CYP$SKIP_ LINES 11 

CYP$START_NEW_ 
DISPLAY_PAGE 11 

CYP$TAB_FILE 11 

riVINtlXTOTTTEi TiilVT'T* rVT7 

BLOCK. 11 

CYP$WRITE_END_OF_ 
LINE 11 

CYP$WRITE_END_OF_ 
PARTITION 11 

C YP$WRITE _ END_ OF_ 
RECORD 11 
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